Errors

Error format

Errors are returned as JSON with a message:

Field	Description
`message`	Human-readable description. Do not parse it: it can change.
`code`	Stable, machine-readable error code. Base your error handling on it.
`fields`	Offending fields, with `unknownField` and `fieldNotUpdatable`.
`candidates`	Connectors to choose from, with `connectorSelectionRequired`.

code is returned by the customers, mandates and reference-data endpoints. The file and upload endpoints return a message only. The token endpoint also returns an error field on its 500 response.

HTTP status codes

Status	Meaning
`400`	The request is invalid. Fix it before retrying.
`401`	The ID token is missing, invalid or expired, or the user cannot use the API. Refresh the token.
`403`	The API key is missing or invalid, a scope is missing, or the user has no access to the resource.
`404`	The resource does not exist or is not visible to the user.
`409`	Conflict with the current state (already exists, already archived, already acknowledged…).
`422`	The request is valid but cannot be processed as is. See the error code.
`429`	Rate limit or quota exceeded.
`500`	Unexpected error. Retry later.
`502`	Upload credentials could not be issued. Retry later.

See also: Rate limits

Error codes

Code	Status	Meaning
`invalidPayload`	400	The body is not a JSON object, or a required field is missing or invalid.
`unknownField`	400	The body contains fields the endpoint does not accept. See `fields`.
`fieldNotUpdatable`	400	The field cannot be changed with `PATCH /customers/{customerId}`. See `fields`.
`invalidIdentifier`	400	The customer or mandate identifier is malformed.
`invalidEnterpriseNumber`	400	The enterprise number is not valid.
`invalidIban`	400	The IBAN is not valid.
`forbiddenScope`	403	Your API key lacks the scope the endpoint requires.
`accessDenied`	403	The customer exists but is outside the user’s access.
`belongsToAnotherTenant`	403	The enterprise number or IBAN is already registered by another accounting firm. To move a customer between firms, the accountant must contact Codaclean support to start a transfer procedure, which requires the end customer’s agreement.
`customerNotFound`	404	The customer does not exist or belongs to another accounting firm.
`ibanNotFound`	404	The IBAN is not linked to this customer.
`payrollProviderNotFound`	404	Unknown payroll provider code, or not linked to this customer.
`mandateNotFound`	404	The mandate does not exist or is not visible to the user.
`bankNotSupported`	404	Codaclean cannot request a mandate for this bank.
`customerAlreadyExists`	409	A customer with this enterprise number already exists in the accounting firm.
`customerAlreadyArchived`	409	The customer has been archived.
`ibanAlreadyInUse`	409	The IBAN is already linked to a customer of the accounting firm.
`payrollProviderAlreadyLinked`	409	The payroll provider is already linked to this customer.
`mandateAlreadyRequested`	409	A mandate request already exists for this customer and bank account or payroll provider.
`connectorSelectionRequired`	422	Several connectors match the bank. Call again with one of the `candidates`’ `connectorId`.
`connectorUnavailable`	422	No usable connector for this bank, or the `connectorId` sent is unknown.

See also: Scopes · Data access

Customers of another accounting firm

The API never reveals another accounting firm’s data. Two cases can occur:

You read or change a customer by its identifier and it belongs to another firm: 404 customerNotFound, exactly as if it did not exist.
You create a customer or add an IBAN that another firm already registered: 403 belongsToAnotherTenant. The call cannot succeed, so the API tells you why, without naming the other firm.

Upload errors

The upload endpoints return these values in message:

Message	Status	Meaning
`upload_not_allowed`	403	Uploading is not enabled for the accounting firm. Contact Codaclean.
`sts_assume_role_failed`	502	The credentials could not be issued. Retry later.

Get started

Concepts

Guides

Authentication

Utilities

Customers

Bank accounts

Customer payroll providers

Mandates

Reference data

CODA files

CODB files

Error format

HTTP status codes

Error codes

Customers of another accounting firm

Upload errors

​Error format

​HTTP status codes

​Error codes

​Customers of another accounting firm

​Upload errors

Error format

HTTP status codes

Error codes

Customers of another accounting firm

Upload errors