Error Handling

Error Format

All errors follow a consistent format:

{
  "error": {
    "type": "validation_error",
    "message": "title is required",
    "status": 400
  }
}

Error Types

Examples

400 — Validation Error

Missing a required field:

curl https://app.alert24.io/api/v1/incidents \
  -X POST \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "error": {
    "type": "validation_error",
    "message": "title is required",
    "status": 400
  }
}

401 — Authentication Error

Missing or invalid Bearer token:

curl https://app.alert24.io/api/v1/incidents

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid or missing API key. Provide a valid Bearer token.",
    "status": 401
  }
}

403 — Authorization Error

API key has read scope but the endpoint requires write:

{
  "error": {
    "type": "authorization_error",
    "message": "API key missing required scope: write",
    "status": 403
  }
}

404 — Not Found

Resource doesn't exist or belongs to a different organization:

{
  "error": {
    "type": "not_found",
    "message": "Incident not found",
    "status": 404
  }
}

429 — Rate Limit Error

See Rate Limits for details.

500 — Server Error

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred",
    "status": 500
  }
}

If you encounter persistent 500 errors, contact support with the X-Request-Id header value from the response.

Tips

• Every response includes an X-Request-Id header. Include it when reporting issues.
• Check the type field, not just the HTTP status, to understand the specific error.
• Validation errors tell you exactly which field is missing or invalid in the message.