Status codes and errors
Learn about status codes and errors of Codat's APIs
The following page describes the status codes and standard error responses used in the Codat API.
Status codes
| Status code | Explanation |
|---|---|
| 200 | Success |
| 202 | Accepted (pending) |
| 400 | Bad Request: The server can't process the request because of an apparent client-side error. |
| 401 | Unauthorized: The supplied Codat API key is incorrect. |
| 402 | Payment Required: An account limit has been reached. The type of account limit is described in the error property: - Company limit exceeded: You have exceeded the 50-company limit that applies to a Free trial. We recommend that you delete any companies you no longer need and retry the request. - SyncSettingsValidationException: Sync schedule not allowed: You have requested an hourly sync schedule; this functionality is not included in the Free trial. - Payment Required: Your Free account is older than 365 days and has expired. Please contact our solutions team to upgrade your plan. For example responses, see Example account limit errors. |
| 403 | Forbidden: This error is returned in the following scenarios: You're using an outdated API key or a key not associated with that resource. - A downstream endpoint can't be accessed. - You're attempting to access an endpoint you are not authorized for. |
| 404 | Not Found: This error is returned in the following scenarios: - The requested resource could not be found. - The data type is not supported by the underlying platform. In this case, the error message is: "Datatype [name] not supported by platform(s) [name]". |
| 405 | Method Not Allowed: You are attempting to use an unauthorized method. |
| 409 | Conflict: The resource is not ready. If syncing a data set, this could mean that either: - The data set has not been requested. - The syncing of data set has not been completed. - The request exceeds the permitted number of values (e.g. creates more than 10 API keys). |
| 429 | Too Many Requests: You have made too many requests in a given amount of time; please retry later. Review our rate limits for full details of exceeded requests. |
| 500 | Internal Server Error: There is a problem with our server. Please try again later. |
| 503 | Service Unavailable: The Codat API is temporarily offline for maintenance. Please try again later. |
Example account limit errors
When an API request causes an account limit to be exceeded, you'll receive a 402 response code. The response body indicates which account limit was exceeded.
50-company limit
Error response from POST /companies when you have exceeded the 50-company limit that applies to the Free trial.
For example:
{
"statusCode": 402,
"service": "PublicApi",
"error": "CompanyValidationException: Company limit exceeded",
"correlationId": "00000000-0000-0000-0000-000000000000",
"validation": {
"errors": [
{
"itemId": "Company",
"message": "Company limit exceeded. Learn more at https://docs.codat.io/using-the-api/errors",
"validatorName": "CreateCompany"
}
],
"warnings": []
}
}
365 day free account limit
Error response when your account has expired and you make a request to any endpoint. This error is returned if your Free account is older than 365 days and has expired.
{
"statusCode": 402,
"service": "PublicApi",
"error": "Payment Required",
"correlationId": "00000000-0000-0000-0000-000000000000",
"validation": {
"errors": [
{
"message": "Account expired. Learn more at https://docs.codat.io/using-the-api/errors",
}
],
"warnings": []
}
}
Correlation IDs in error responses
The content of an error response includes a more detailed error message and a correlationId, which can be used to identify a particular response. Please include the correlationId in text format if you are contacting Codat support regarding an error.
{
"statusCode": 404,
"service": "QuickbooksOnline",
"error": "InvoicePdfNotFoundException: Invoice not found for company 360cb9b3-d9cf-4f66-b8db-8a3523fe3dc5 and invoice ID 12345",
"correlationId": "131f0225-5467-421a-b179-4531d6b4a942"
}
Status codes in asynchronous write responses
Status codes for write operations created in the Codat API might be different from the status codes returned in the responses from the service providers.
When a write operation is created in the API, some service providers may use a 202 Accepted code, which implies that the request has been accepted for processing, but the processing has not completed. However, the write API may return a 200 Success code for the write operation successfully created in the Codat API.
You've learned about error codes you might encounter while using the API.