HTTP Error Status Codes

When a request fails, the API responds with a non-2xx HTTP status and a JSON body in the following shape:

{
  "code": "BAD_REQUEST",        // stable machine-readable error code
  "message": "Bad Request",     // human-readable description
  "details": {                  // present only on validation errors
    "field": { "message": "..." }
  }
}

Branch on the code field. It is stable and safe to switch on in your application. The message field is intended for humans and may change without notice. The details object is present only for validation errors, and maps each failing field to a message explaining why it was rejected.

Codes

Code	HTTP status	What it means	How to handle
`BAD_REQUEST`	400	The request was malformed or contained invalid input.	Check the request against the endpoint's schema and retry.
`VALIDATION_ERROR`	422	One or more fields failed validation.	Inspect `details` for the offending fields and correct them.
`NOT_AUTHORIZED`	401	Authentication is missing or invalid.	Provide a valid API key or token and retry.
`FORBIDDEN`	403	You are authenticated but not permitted to perform this action, for example when the API key, the agent it belongs to, or the organization user who owns it has been deactivated.	Do not retry without the required permissions.
`NOT_FOUND`	404	The requested resource does not exist, or the URL is invalid.	Verify the identifier and URL in the request path.
`NOT_ELIGIBLE`	409	The account or resource is not eligible for this operation, for example a seller service that is still pending approval.	Do not retry until the eligibility requirements are met.
`CONFLICT`	409	The request collides with something that already exists: an organization user with the same email, an agent, agent group, or organization name already in use, or an ungrouped buyer agent for a user who already has one. Nothing is created or changed.	Choose a different name or look up the existing record instead of creating a new one. Do not retry unchanged.
`PAYMENT_DECLINED`	400	The payment was declined.	Use a different payment method and retry.
`PAYMENT_ERROR`	402	Payment is required or could not be completed.	Ensure the account is funded before retrying.
`SERVER_ERROR`	500	Skyfire could not complete the request. The request itself was acceptable.	Retry with backoff. If it persists, contact support with the request's timestamp.

Handling errors

Branch on code, not the HTTP status alone. Multiple codes can share a status. For example, BAD_REQUEST and PAYMENT_DECLINED are both 400.
A 4xx response means something in the request needs to change. Retrying it unchanged will fail again. Fix the input, authentication, or permissions first, then retry.
On a VALIDATION_ERROR, use the details object to pinpoint which fields were rejected and why, rather than parsing the message.
A 5xx response is the only kind worth retrying unchanged. Wait and retry with backoff; a 4xx will fail again until the request changes.