---
updatedAt: 2026-07-14T04:43:49.000Z
agentTools:
  projectIndex: https://docs.skyfire.xyz/llms.txt
---

# HTTP Error Status Codes

The error response shape, the full list of stable error codes, and how to handle each one.

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

```json
{
  "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 is valid but a related resource is inactive. | 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.     |
| `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.                |

## 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`.