Error Handling

The API uses standard HTTP status codes. A 2xx status means success; 4xx means the request was rejected; 5xx means something went wrong on our side.

Error shape

Errors return a JSON body with a machine-readable code, the HTTP status, and a data object carrying the human-readable detail:

{
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "Bad Request",
  "data": { "message": "instagram requires at least 1 media file." }
}

Schema-validation failures (422) return field-level detail under data.fieldErrors:

{
  "code": "INPUT_VALIDATION_FAILED",
  "status": 422,
  "data": {
    "formErrors": [],
    "fieldErrors": { "caption": ["Expected string, received undefined"] }
  }
}

Read the human-readable reason from data.message (or data.fieldErrors for 422).

Common status codes

Status	Meaning
`400`	Bad request — malformed JSON or invalid parameters
`401`	Unauthorized — missing, invalid, or revoked API key
`403`	Forbidden — the key can't access this resource
`404`	Not found — the resource doesn't exist in this workspace
`422`	Validation error — the body failed schema validation
`429`	Too many requests — you hit a rate limit
`5xx`	Server error — safe to retry with backoff

Retrying

TIP

Retry and responses with exponential backoff. Do not retry validation errors — fix the request instead. See for handling.