Conventions  /  Errors

Errors

Every error uses the same envelope, with no variation by endpoint. Parse error.type first (a small, closed set), then error.code for the specific case.

400 Bad Request
{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_field",
    "message": "Missing required field: trigger.type",
    "param": "trigger.type"
  }
}

param is present only when the error points at a specific field. message is for logs, not for parsing.

Status codes

Code
When
200
Successful GET, PATCH, DELETE, or idempotent re-POST.
201
A POST created a new resource.
400
Validation failure, malformed JSON, or a bad cursor.
401
Missing or invalid API key.
402
Account state doesn't allow this change (billing).
403
Valid key, but it lacks the required permission.
404
Resource doesn't exist, or belongs to another account.
409
Conflict, such as a subscription that already exists.
429
Rate limited. Check the Retry-After header.
502
A cross-service write failed. Safe to retry.
503
Service not configured.

Error types

invalid_request_error400
Malformed request: bad JSON, failed validation, a bad ID, or a bad cursor.
authentication_error401
No API key, or the key is invalid or revoked.
payment_required402
The account's billing state blocks this change (trial expired, past due, canceled, or no subscription).
permission_error403
Valid key, but it lacks the permission this endpoint needs.
not_found_error404
The resource doesn't exist, or it isn't yours.
rate_limit_error429
Over quota. The Retry-After header carries seconds until reset. See Rate limits.
idempotency_error400
An Idempotency-Key was reused with a different body within 24 hours.
delivery_service_error502
A cross-service write failed. Safe to retry.
internal_error5xx
An unexpected server error. Retry with backoff.