---
updatedAt: 2026-10-01T07:18:12.000Z
agentTools:
  projectIndex: https://developer.spendesk.com/llms.txt
---

# Error Handling

The error model (code, detail, source, correlation ID), the HTTP codes the API returns, and partial success (207) on bulk updates.

The Spendesk API follows standard conventions using HTTP response codes.

## Error Model

Errors share a consistent model, which provides additional detail, where necessary, to help resolve the error(s):

```json
{
  "correlationId": "a3b8e2f1-4c5d-4e6f-9a0b-1c2d3e4f5a6b",
  "errors": [
    {
      "code": "BAD_REQUEST_INCORRECT_OR_MISSING_FIELD",
      "detail": "There is a validation error with incorrect field in request body. Please fix and repeat your request.",
      "source": "type"
    },
    {
      "code": "BAD_REQUEST_INCORRECT_OR_MISSING_FIELD",
      "detail": "There is a validation error with incorrect field in request body. Please fix and repeat your request.",
      "source": "bookkeepingStatus"
    }
  ]
}
```

* `errors` - one or more errors, each with a stable `code`, a human-readable `detail` and, for validation errors, the `source` field at fault;
* `correlationId` - the identifier of your request, also returned in the `x-correlation-id` response header. Include it when you contact support about a failed call.

## HTTP Codes

These are the common standard HTTP response codes that will be used when there is an error in your request:

| HTTP Code | `code`                                   | Description                                                                                                                                                 |
| :-------- | :--------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400       | `BAD_REQUEST_INCORRECT_OR_MISSING_FIELD` | Bad Request - something in the request was not as expected. We will usually provide more details in the response body to allow you to debug.                |
| 401       | `AUTHENTICATION_ERROR`                   | Authentication Error - check your access token.                                                                                                             |
| 403       | `FORBIDDEN_ERROR`                        | Forbidden - you're trying to access something you don't have the correct privileges for. Try reviewing the scope of your API credentials or access token.   |
| 404       | `NOT_FOUND`                              | Not Found - the resource you're requesting doesn't exist. List endpoints also return 404 for a page past the last one — see [Pagination](https://developer.spendesk.com/reference/pagination).   |
| 409       | `CONFLICT_ERROR`                         | Conflict - the request conflicts with the current state of the resource, or a limit was reached (for example the number of open payable snapshot requests). |
| 413       | `LARGE_BODY_ERROR`                       | Payload Too Large - the request body or the uploaded file is too large.                                                                                     |
| 415       | `UNSUPPORTED_MEDIA_TYPE`                 | Unsupported Media Type - the type of the uploaded file is not accepted.                                                                                     |
| 422       | -                                        | Unprocessable - the request is valid but cannot be applied in the resource's current state. The body gives a `reason` instead of the `errors` list.         |
| 429       | `TOO_MANY_REQUESTS`                      | Too Many Requests - you have made too many requests and hit the rate limit. You should wait and retry — see [Rate Limiting](https://developer.spendesk.com/reference/rate-limiting).             |
| 500       | `INTERNAL_SERVER_ERROR`                  | Internal Server Error - something has gone wrong on our side, best to contact our support with the `correlationId`.                                         |
| 503       | `SERVICE_UNAVAILABLE_ERROR`              | Service Unavailable - the feature is temporarily unavailable (for example payable snapshots). Retry later.                                                  |

## Partial success on bulk updates

Bulk updates — [Update bookkeeping status of payables](https://developer.spendesk.com/reference/v1-put-payables-bookkeeping-status) and [Update state of settlements](https://developer.spendesk.com/reference/v1-put-settlements-state) — return **207 Multi-Status** when some items were updated and others were not. Check the `outcome` of each item: `updated`, or `notUpdated` with a `reason` such as `notFound` or `invalidState`.

```json
{
  "updatedPayables": [
    { "id": "bc9cef35-401d-4ea4-b384-ed725e6685cf", "outcome": "updated" },
    { "id": "5d1f0a2e-7b6c-4e3d-9f8a-2b1c0d9e8f7a", "outcome": "notUpdated", "reason": "invalidState" }
  ]
}
```