Errors

Every error returns the same shape, so you can handle failures in one place. The HTTP status tells you what kind of problem it is; the code tells you exactly which one.

Draft documentation. Codes may be added before the beta.

The shape

{
  "error": {
    "code": "validation_error",
    "message": "Enter a valid email address."
  }
}

Read message for a human-readable explanation. The code is stable; the message may be reworded.

Codes

Code	Status	Meaning
unauthorized	401	The key is missing, revoked or wrong.
not_found	404	The resource does not exist or is not yours.
validation_error	400	The body or query has a missing or invalid field.
conflict	409	The action conflicts with the current state.
rate_limited	429	Too many requests. Retry after the given delay.
internal_error	500	Something broke on our side. It is safe to retry.

Retries

Retry 429 and 500 with backoff.
Do not retry 4xx errors other than 429. Fix the request first.
Use an idempotency key on POST requests that create or send something, so a retry cannot duplicate it.

Authentication API reference