Skip to main content

​
Envelope

Every error response uses the same shape: 
{
  "errorCode": "VALIDATION_ERROR",
  "message": "Human-readable description.",
  "details": { "...": "optional, error-specific" }
}
The errorCode is stable across releases. Switch on it programmatically. The message is meant for humans and may change.

​
Status codes

CodeMeaning
200Success
202Accepted — work started asynchronously, such as Brand Kit extraction or email processing
204Success, no content
400Bad request — payload validation failed
401Missing or invalid x-api-key
403Key valid but lacks the required scope
404Resource not found, or belongs to a different organization
409Conflict — concurrent retry, idempotency lock held, or terminal-state operation
410Gone — a temporary resource or token has expired
422Unprocessable — semantic validation failed (e.g. template incomplete, idempotency key reused)
429Rate limited
501Not implemented

​
Common error codes

  • MISSING_CREDENTIAL - no supported credential was supplied (401).
  • INVALID_API_KEY - x-api-key is invalid or revoked (401).
  • INSUFFICIENT_SCOPE or API_KEY_SCOPE_INSUFFICIENT - key valid but missing a required scope (403). Includes required field listing the needed scopes.
  • NOT_FOUND - the resource doesn’t exist or belongs to another organization (404). The API never reveals which.
  • IDEMPOTENCY_KEY_REUSED - same Idempotency-Key header sent with a different request.
  • VALIDATION_ERROR - the request is structurally valid but semantically rejected, such as a template missing a subject or sender profile.

​
Cross-organization access

Reading or writing a resource that belongs to another organization always returns 404 — never 403. This prevents an attacker (or a confused integration) from enumerating which IDs exist in other orgs.