API reference

Errors

The error envelope and every code the API returns

Every error the API produces has the same shape: an error object with a stable code and a human-readable message.

A validation failure lists the offending fields in details:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request",
    "details": [
      { "field": "content", "message": "Content is required." }
    ]
  }
}

Tip

Branch on code, not message; messages can change.

Error codes

Status	Code	When
400	BAD_REQUEST	The request body is not valid JSON.
400	VALIDATION_ERROR	The request body or query string failed validation, or `identifier` is missing.
401	UNAUTHORIZED	The Authorization header is missing, malformed, or the key is invalid, revoked or expired.
402	INSUFFICIENT_CREDIT	The project does not have enough credit to accept the request. `balance` and `required` are included.
403	PROJECT_SUSPENDED	The project is suspended because its credit balance stayed negative.
404	NOT_FOUND	No such route, or no memory with that id for this identifier.
409	MEMORY_LIMIT_REACHED	The identifier has reached its stored-memory cap.
500	INTERNAL_ERROR	Something went wrong on our side.
503	SERVICE_UNAVAILABLE	The platform is in maintenance, or a usage check could not be completed.

Note

BAD_REQUEST means the body could not be parsed as JSON. A missing Content-Type: application/json header does not give this error; it makes the body read as empty, which fails validation with VALIDATION_ERROR.

Warning

Some failures happen at the edge, before the request reaches the API, and do not use the envelope:

Oversized body. Larger than 1,048,576 bytes is rejected with 413; the body is JSON, but error is a plain string, not an object with code and message.
Timeout. Requests that run longer than 20 seconds are cut off with a gateway error.

Authentication

How to send your API key and what every request needs

Rate limits

How requests are gated