Error Handling Best Practices

December 19, 2022


Erply API's response always contains a header block, named "status". Within that block, there is a field named "errorCode". If the field has a value of 0, the call has completed successfully. If it contains a four-digit code, an error has occurred.

See the full list of error codes.

As an example, an API call to add a new product (saveProduct) may return the following response:

{
   "status":{
       "request":"saveProduct",
       "requestUnixTime":...,
       "responseStatus":"error",
       "errorCode":1061,
       "errorField":null,
       "generationTime":...,
       "recordsTotal":0,
       "recordsInResponse":0
   },
   "records":null
}

In this particular case, the user does not have the permissions to add new products. (Error code 1061: No adding rights (in this module).)

We strongly encourage you to handle not only the various error codes, but also cases when your application does not receive a response at all:

  • The request times out.
  • The server returns an empty response.
  • The server returns invalid JSON.
  • The server returns a 400- or 500-series HTTP status code.

Appropriate error handling procedures may be different depending on whether the API client is an interactive application or a server-side script.

Error Handling in an End-User Application

Try to draw a line between errors that are likely caused by user, or account setup, or a particular dataset — and errors which may point to flaws in application logic. 

User Errors and Setup Errors

User- or data-centric errors, to bring just a few examples, are:

  • 1001: Account not found. (Did the user mistype their account number?)
  • 1006: Required module missing on this account, please contact Erply customer support.
  • 1012: A parameter must have a unique value. (For example: this product code already exists, please pick a new one.)
  • 1017: Document has been confirmed and its contents and warehouse ID cannot be edited anymore.
  • 1148: User does not have access to customer data.

In case of such errors, it would be best to show an error message, to notify the user about the issue and suggest what they should do next.

Error codes 1054 and 1055 mean that current session has expired. The application should pop up a login form and ask the user to re-authenticate.

Application Logic Errors

Application logic errors, on the other hand, should be logged and reviewed by the developer. These may indicate cases where the application is not following API documentation, or has made mistaken assumptions. A few examples of application-logic errors are:

  • 1005: Unknown API call
  • 1010: Required parameters missing. (The application should have ensured that it got the required input from user.)
  • 1016: Invalid value
  • 1020: Bulk API call contained more than 100 sub-requests (max 100 allowed). The whole request has been ignored.

The application should most likely display an error message, too, to let the user know that an abnormal situation has occurred. Crucially though — in these cases, the user is unable to resolve the problem. If the application does not log these errors, you will effectively rely on the user reporting those issues to you.

Thus, we recommend to identify the specific errors that user can resolve themselves, and log everything else. 

Exceeded Quota

Error code 1002 indicates that the quota of API limits has been exceeded for the current hour. API calls will be allowed again when the next hour starts.

HTTP status code 429 indicates that Erply's servers are enforcing rate limiting (in case there is an abnormal amount of API trafic from your IP address to Erply's servers). The error will clear in a short period of time, typically 10 seconds.

Service Errors

These indicate that there is a temporary problem with the service. It might eventually resolve; the application can try re-sending the call right away. If the retried call fails, too, the application or the user should retry at a later time. If the application was trying to store data in Erply, it must save it locally, to avoid losing it altogether.

A service error might be indicated by:

  • HTTP 400- or 500-series status code
  • Timeout
  • Empty response
  • API error code 1000

To Retry Or Not?

An immediate (or slightly delayed) retry is appropriate if a service error occurs (eg. error code 1000).

If the request is of critical nature, the application can also retry in case of every unknown error code.

Known user errors and setup errors will NOT resolve even in case of a retry, so re-sending the request does not help.

Error code 1002 will resolve at the beginning of next hour.

Error Handling in an Integration, or an API Script

Error codes 1054 and 1055 means that the current session has expired. Perform a new verifyUser call with the script's credentials.

If an authentication request fails with error codes 1051 and 1052, the credentials are wrong (user has been deleted from Erply, or its password updated). Re-sending the call will have no effect!

Error code 1002 means that the number of requests in the current hour has reached the allowed limit (by default, 1000 requests). The script should save its state and resume work the next hour.

Log other errors and review the log regularly, to ensure that the script performs its duties.