Error Handling

​

Problem Details

Lucca Apis implements the “Problem Details” standard to describe errors (see RFC 7807).

The Problem Details standard is a way to respond with machine-readable error messages. So make sure to read them, as they will definitely help your figure out the cause for errors you may encounter.

HTTPS/1.1 400 Bad Request
Content-Type: application/problem+json

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
        "Id": [
            "The id field is required."
        ],
        "Date": [
            "The date field is required."
        ]
    }
}

​

Common HTTP Status Codes

Note: The Lucca API strives to stick to the intended semantics of the HTTP status codes.

​

Error Handling

Depending on the kind of error, you may use one or all of the following strategies in order to handle it:

The Lucca API offers many kinds of errors. They can reflect external events, like declined payments and network interruptions, or code problems, like invalid API calls.

To handle errors, use some or all of the techniques in the table above. No matter what technique you use, you can follow up with our recommended responses for each error type.

API calls to the Lucca API may result in error.

In general, 4xx status codes indicate an error on the client side, and 5xx errors an error on the server side.

Exception being the 429 HTTP status code, which indicates that you reached the server rate-limit, and as such you should retry sending your request later.

​

Handling 4xx Errors

When receiving 4xx errors, first refer to the response content, as it should be a Problem object that gives clear pointers about the reasons for the error. Most often, 4xx errors are caused by:

• lack of authentication (401), in which case your access_token is certainly invalid or has expired ;
• a poorly formatted payload infringed validation rules on the payload (400) or query parameters typing and/or requirements, in which case you should double check the API Reference ;
• insufficient access rights (403 on write requests and 404 on read requests), in which case you should make sure your access_token has the required oAuth scopes.

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "instance": "https://example.ilucca.net/lucca-api/leaves/1573",
    "errors": {
        "endsOn": [
            "Invalid period: StartsOn should be before EndsOn."
        ],
        "employeeId": [
            "The employeeId query parameter is required."
        ]
    },
    "extensions": {
        "traceId": "|78777424-49cc27e04281bbfc."
    }
}

​

Handling Deprecation Warnings

Whenever a version of the Lucca API is marked as deprecated, all server responses will have both:

• a Deprecation HTTP header which indicates the date from which the version was marked as deprecated ;
• a Sunset HTTP header which indicates the date from which the version will no longer respond.

​

Handling 5xx Errors

5xx errors are most likely not caused by you, but rather by some unexpected problems with our servers. If so, then you should go to our status page which will give you more information about the problem, its causes and an E.T.A. towards its resolution.

If the problem is absent from our status page even after some time has passed, then you should contact us through our support.

Once the problem is fixed, you may retry your requests.

​

Browse Logs

Coming soon.