# Error Codes

API responses use standard HTTP status codes:

| Code | Description |
|---|---|
| `200` | The request (GET or PUT) completed successfully. |
| `201` | The create request (POST) completed successfully. |
| `204` | The delete request completed successfully (no content in the response). |
| `400` | The request body is malformed or failed validation (field errors are returned in `errors`). |
| `401` | The access token is missing, invalid or expired, or on the Admin API the client has no permission for this operation. |
| `403` | The client does not have the required permissions for this operation. |
| `404` | The requested object was not found on the server. |
| `405` | This operation type (GET, POST, PUT or DELETE) is not allowed. |
| `429` | Too many requests were made within a certain period. |
| `500` | An error occurred on the server and the request could not be fulfilled. |
| `503` | The server is currently not serving (down or unreachable). |

Validation errors are returned with `400`, not `422`.

## Error body

Application errors (`400`, `403`, `404`, `500`, and the Admin API permission error `401`) share the same JSON body. `errorMessage` is translated according to the `x-ideasoft-locale` request header.

```json
{
  "code": 400,
  "errorMessage": "Validation Error.",
  "errorCode": 300001,
  "errors": {
    "name": "This value should not be blank."
  }
}
```

| Field | Description |
|---|---|
| `code` | HTTP status code. |
| `errorMessage` | Error message. |
| `errorCode` | Application specific error code: `300001` for validation errors, `0` when undefined. |
| `errors` | Validation errors. The Admin API returns a field name → message object, the Store API returns an array of `{field name: message}` objects. |

When the access token is missing, invalid or expired, the `401` response uses the OAuth error format:

```json
{
  "error": "invalid_grant",
  "error_description": "The access token provided is invalid."
}
```

:::info{title="Retrying"}
For `429` and `5xx` responses, retry the request with exponential backoff. Do not retry `4xx` errors — fix the request first.
:::

## Cloudflare Errors

For Cloudflare-originated errors returned before the endpoint is reached, see [Cloudflare error codes](https://developers.cloudflare.com/support/troubleshooting/cloudflare-errors/).
