Errors and the response envelope

The envelope

Every response — success or error — shares one shape.

{
  "code": 200,
  "message": "Success",
  "status": "SUCCESS",
  "data": { },
  "errors": [ ]
}

integer

The HTTP status code, repeated in the body.

string

A human-readable summary of the outcome.

enum

Either SUCCESS or ERROR.

object | null

The payload. null on error.

array

A list of {code, message, field} objects. Empty on success. Body-validation failures return one entry per offending field.

Check status, not just the HTTP code. A response is only successful when status is SUCCESS and errors is empty.

HTTP	Meaning
`400`	Validation failed, or the key lacks the required permission. Read `errors[]` for the offending fields.
`401`	Missing or invalid API credentials. See Authentication.
`404`	No such resource, or it belongs to another partner.
`405`	Wrong verb on a valid path.
`409`	The request conflicts with the current state of the resource.
`422`	The requested mode or option is not available yet.
`500`	Unexpected server error.
`503`	Credentials could not be verified right now. Retry with backoff.

There is no 429. Rate limits surface as 400, so do not build retry logic around a 429 response.

Code	Retry?
`400`, `401`, `404`, `405`, `409`, `422`	No. Fix the request or the credential.
`500`	Yes, with backoff.
`503`	Yes, with backoff. This is the transient one.

Never blindly retry a write that may have succeeded — Submit transaction in particular. Read the transaction back before resubmitting it.