​
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.
CodeNameDescriptionRetry?
400Bad SyntaxCommon validation problem. You may want to double check the request body complies with the spec, and the query parameters as well. You may find further details in the response body.❌ No
401UnauthorizedServer could not authenticate you. Make sure your access token is valid and has not expired.❌ No
403ForbiddenYour HTTP requests was forbidden by the server. Double check what you’re attempting to achieve is allowed by the API Reference and/or your level of access.❌ No
404Not FoundThe requested resource does not exist, was deleted, or you do not have access to it (access rights).❌ No
405Method Not AllowedThe HTTP method you invoked is not supported on the corresponding API path. Please refer to the API Reference.❌ No
429Too Many RequestsYou exceeded the API rate-limit.✅ Yes (later)
500Internal Server ErrorSomething unexpected happened. We were notified and will be investigating the problem. Please refer to our status page to know more.✅ Yes (maybe)
503Service UnavailableThe Lucca API is down. We’re on it to make sure it will be back up as soon as possible. Please refer to our status page to know more.✅ Yes

Errors due to limits being reached

Learn more about the limits of the Lucca API usage.

​
Error Handling

Depending on the kind of error, you may use one or all of the following strategies in order to handle it:
StrategyPurposeWhen needed
Handling errors (below)Recover whenever an API request fails.Always
Monitor webhooksReact to failed event deliveries.Often
Browse logs (below)Investigate past problems.Sometimes
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."
    }
}
Other 4xx error types may be due to our API limits

​
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.
Therefore, you should definitely monitor these headers in all of your requests in order to be notified whenever a script uses a deprecated API version.

​
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.