Error Codes

Error format

Errors are JSON objects with an error field. Some include more detail:

{
  "error": "Forbidden",
  "message": "Requires one of the following roles: owner, admin",
  "code": "subscription_required",
  "details": []
}

Field	When present
`error`	Always: a short description
`message`	Authentication and authorization errors, and insufficient credits
`code`	Machine-readable code for some errors (see below)
`details`	Validation errors, e.g. `Invalid buffer configuration`
`credits` / `required`	Insufficient credits (`429`)

A body that isn't valid JSON is rejected before it reaches the API, with 400 and an HTML "Bad Request" page.

Success codes

Status	Returned by
`200 OK`	Reads, updates (`PATCH`) and actions such as DLQ retry
`201 Created`	Creating projects, buffers, API keys and clones
`202 Accepted`	Ingest: the webhook is stored and will be delivered
`204 No Content`	Deleting projects, buffers and DLQ entries, revoking API keys

Ingest responses:

{ "status": "accepted", "messageId": "5b0c6f0e-…", "itemId": "0e6d1c2b-…" }

{ "status": "accepted", "messageId": "evt_unique_123", "duplicate": true }

Client errors

400 Bad Request

The request is invalid. Examples:

`error`	Cause
`projectId and name are required`	Missing fields when creating a project
`bufferId, projectId, and name are required`	Missing fields when creating a buffer
`Invalid buffer configuration`	Buffer settings failed validation; see `details`
`Project not found`	Creating a buffer in a project that doesn't exist or isn't yours
`Cannot delete project with existing buffers`	Delete the project's buffers first
`Buffer is disabled`	Ingest into a disabled or auto-paused buffer
`Buffer does not belong to this project`	Wrong project ID in the ingest URL
`Could not extract group key from request`	The payload and headers don't contain the group key
`name is required` / `Invalid role`	Invalid API key creation request

401 Unauthorized

Authentication failed.

`error` / `message`	Cause
`Missing or invalid Authorization header`	No `X-API-Key` and no `Authorization: Bearer` header
`Invalid or revoked API key`	The key doesn't exist or was revoked
`Invalid or expired token`	The Firebase ID token is invalid or expired
`Missing signature header` / `Invalid signature`	Ingest with source verification enabled

403 Forbidden

You're authenticated but not allowed to do this.

`error` / `message`	Cause
`Requires one of the following roles: …`	Your role is too low; see roles
`Access denied to this customer`	The request names another account's `customerId`
`API key does not have access to this buffer`	Ingest with a key from another account or not scoped to the project
`Cannot create API key with higher role than your own`	Key creation above your role
`Cannot create API key with broader project access than your own`	Key creation outside your project scope
`Email address must be verified` (`email_not_verified`)	Password account without a verified email
`User not associated with a customer`	The signed-in user has no account yet
`An active subscription is required to buy credit packs` (`subscription_required`)	Credit pack checkout without a subscription

404 Not Found

The resource doesn't exist or belongs to another account: Buffer not found, Project not found, DLQ item not found, API key not found, Credit pack not found.

409 Conflict

`error`	Cause
`Project already exists` / `Buffer already exists`	The ID is taken. IDs are global, so choose unique ones
`Maximum 10 active API keys per customer`	Revoke unused keys first
`API key is already revoked`	Nothing to do
`Credit pack is not available for purchase yet` (`PACK_NOT_AVAILABLE`)	The pack can't be bought yet

429 Too Many Requests

On ingest, your credit balance is too low for the payload:

{
  "error": "Insufficient credits",
  "credits": 3,
  "required": 5,
  "message": "Please add more credits to continue receiving webhooks"
}

See Credits & Billing. During extreme bursts the hosting platform itself may also return 429 without a JSON body; retry with backoff.

Server errors

500 Internal Server Error

An unexpected error. Retry with exponential backoff; if it persists, contact support with the endpoint, time and request.

503 Service Unavailable

A dependency is unavailable, for example Payment provider not configured on billing endpoints. Retry later.

Machine-readable codes

`code`	Status	Meaning
`email_not_verified`	403	Verify your email address before using the API with a password account
`subscription_required`	403	Credit packs require an active subscription
`PACK_NOT_AVAILABLE`	409	The credit pack can't be bought yet

Handling errors

Check the status code before reading the body
Retry 5xx and platform 429/503 responses with exponential backoff (for example 1 s doubling up to 60 s)
Don't retry other 4xx without changing the request; for 429 Insufficient credits, add credits first
Log the error, message and code fields
Use stable message IDs (messageId in the body or X-Idempotency-Key) so retried ingest requests aren't stored twice

Error Codes

On this page