Errors & Status Codes

The AeroSelect API uses standardized HTTP status codes and returns structured JSON responses for errors.

HTTP Status Codes

Status CodeMeaning
200 OKRequest successful. Response contains the requested data.
201 CreatedResource created successfully. Response contains the new resource.
204 No ContentRequest successful, no response body (e.g. on DELETE).
400 Bad RequestInvalid request. Check the format and required fields.
401 UnauthorizedMissing or invalid API key. Check the X-API-Key header.
403 ForbiddenAuthenticated, but no permission for this action. Missing scope.
404 Not FoundResource not found. Check the ID in the URL.
422 Unprocessable EntityValidation error. Response contains an errors object with field errors.
429 Too Many RequestsRate limit exceeded. Wait the time specified in the Retry-After header.
500 Internal Server ErrorServer error. Please contact [email protected] with the request ID.

Error Response Format

All error responses follow a unified JSON format:

Error ResponseJSON
{
  "message": "Kurze Fehlerbeschreibung",
  "errors": {
    "field_name": ["Feldspezifische Fehlermeldung"]
  }
}

Validation Errors (422)

For validation errors, the errors object contains the affected fields as keys and arrays of error messages as values:

422 Unprocessable EntityJSON
{
  "message": "The given data was invalid.",
  "errors": {
    "title": ["The title field is required."],
    "location": ["The location field is required."],
    "status": ["The selected status is invalid. Valid values: draft, online, archived."],
    "salary_min": ["The salary min must be a number."]
  }
}

Authentication Errors (401 / 403)

401 UnauthorizedJSON
{
  "message": "Unauthenticated.",
  "errors": {}
}
403 ForbiddenJSON
{
  "message": "This action is unauthorized.",
  "errors": {
    "scope": ["Required scope 'candidates:write' is not granted."]
  }
}

Not Found (404)

404 Not FoundJSON
{
  "message": "No query results for model [Job] 9999",
  "errors": {}
}

Error Handling in JavaScript

error-handling.jsJavaScript
async function apiRequest(url, options = {}) {
  const response = await fetch(url, {
    ...options,
    headers: {
      "X-API-Key": process.env.AEROSELECT_API_KEY,
      "Accept": "application/json",
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  const data = await response.json();

  if (!response.ok) {
    switch (response.status) {
      case 401:
        throw new Error("Ungültiger API-Key");
      case 403:
        throw new Error(`Fehlender Scope: ${data.errors?.scope?.[0] ?? ""}`);
      case 404:
        throw new Error("Ressource nicht gefunden");
      case 422:
        // Validierungsfehler - Felder ausgeben
        const fieldErrors = Object.entries(data.errors ?? {})
          .map(([field, msgs]) => `${field}: ${(msgs as string[]).join(", ")}`)
          .join("\n");
        throw new Error(`Validierungsfehler:\n${fieldErrors}`);
      case 429:
        throw new Error("Rate Limit überschritten");
      case 500:
        throw new Error("Serverfehler - bitte versuche es später erneut");
      default:
        throw new Error(data.message ?? "Unbekannter Fehler");
    }
  }

  return data;
}

Retry Strategy

Not all errors justify a retry. The following table provides guidance:

StatusRetry?Strategy
400NoFix the request format
401NoCheck and renew the API key
403NoAdd scope or replace the key
404NoCheck the ID
422NoFix the input data
429YesExponential backoff with Retry-After header
500YesUp to 3 attempts with increasing delay

Request ID for Support

Every API response contains an X-Request-Id header. Share this with support requests so we can find the request in our logs.