Errors & Status Codes
The AeroSelect API uses standardized HTTP status codes and returns structured JSON responses for errors.
HTTP Status Codes
| Status Code | Meaning |
|---|---|
| 200 OK | Request successful. Response contains the requested data. |
| 201 Created | Resource created successfully. Response contains the new resource. |
| 204 No Content | Request successful, no response body (e.g. on DELETE). |
| 400 Bad Request | Invalid request. Check the format and required fields. |
| 401 Unauthorized | Missing or invalid API key. Check the X-API-Key header. |
| 403 Forbidden | Authenticated, but no permission for this action. Missing scope. |
| 404 Not Found | Resource not found. Check the ID in the URL. |
| 422 Unprocessable Entity | Validation error. Response contains an errors object with field errors. |
| 429 Too Many Requests | Rate limit exceeded. Wait the time specified in the Retry-After header. |
| 500 Internal Server Error | Server 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:
| Status | Retry? | Strategy |
|---|---|---|
| 400 | No | Fix the request format |
| 401 | No | Check and renew the API key |
| 403 | No | Add scope or replace the key |
| 404 | No | Check the ID |
| 422 | No | Fix the input data |
| 429 | Yes | Exponential backoff with Retry-After header |
| 500 | Yes | Up 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.