Error Handling

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):

{
  "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.
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.
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 and Update state of settlements — 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.

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