Error handling

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

For reference, all possible error codes are listed here.

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, 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 (request timeout / empty response received / invalid JSON received). 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- or data-centric errors, to bring just a few examples, are:

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

In case of such errors, it would be best to pop up an error message to notify user about the issue, and suggest a solution if possible.

Application-logic errors, on the other hand, should be logged and reviewed by 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:

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

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.

Error handling in an integration, or an API script

1. Error codes 1054 and 1055 means that current session has expired. Perform a new verifyUser call with the script's credentials.
2. 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!
3. 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.
4. Log other errors and review the log regularly, to ensure that the script performs its duties.