Docs Sign in Get a key

Docs / Platform

Errors

How the Hapti API reports errors. HTTP status codes, error types, stable reason codes and what to do about each of them.

Errors come with an HTTP status and a JSON body that says what went wrong in plain words.

JSON
{
  "error": {
    "type": "invalid_request_error",
    "code": 400,
    "message": "url: an http or https address is required"
  }
}
FieldWhat it holds
error.typeThe family of the error, from the status
error.codeThe HTTP status
error.messageWhat went wrong and how to fix it, for a developer
error.reasonA stable code for some errors, to test in your code

Status codes

StatusTypeMeaningRetry
400invalid_request_errorA field is missing or wrong: read the messageNo, fix the request
401authentication_errorThe key is missing, wrong or revokedNo
402billing_errorNot enough credit, and the task was set to refuse rather than waitAfter adding credit
403permission_errorThe key or the person may not do thisNo
404not_found_errorNo such object in this organisation and modeNo
409conflict_errorThe object is not in a state that allows it, or an idempotency key is in useDepends on the reason
429rate_limit_errorToo many requests: wait for the Retry-After headerYes, after the wait
500api_errorAn error on our sideYes, with an idempotency key
502engine_errorThe browser could not be reachedYes, with an idempotency key
503unavailable_errorA service is not available for a momentYes

Reason codes

ReasonStatusWhat to do
insufficient_credit402Add credit, or let tasks wait with on_insufficient_credit: "pause"
user_limit_reached429The person reached a limit you set: see limits per person
idempotency_conflict409The same idempotency key was used with another request: use a new key
idempotency_in_progress409A request with this key is still running: retry in a moment
idempotency_key_invalid400Use 1 to 255 visible characters, without spaces
version_unknown400Hapti-Version is not a known version: see Versioning
live_only402This needs a live key, for example a phone number
already_disputed409This task already has a dispute

Request ids

Every answer carries a Request-Id header. Give it to support, or find the request with its body in Developers, Requests in the console.

Retrying safely

Retry 429 and 5xx answers with a growing wait. Send an idempotency key with every POST, so that a retry never does the work twice. The official libraries do both for you.