Error Handling

Problem Details

The Lucca API 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. Make sure to read them, as they will definitely help you 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.

Code	Name	Description	Retry?
`400`	Bad Request	Common validation problem. Double check that the request body complies with the spec, and verify the query parameters as well. You may find further details in the response body.	❌ No
`401`	Unauthorized	Server could not authenticate you. Make sure your access token is valid and has not expired.	❌ No
`403`	Forbidden	Your 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
`404`	Not Found	The requested resource does not exist, was deleted, or you do not have access to it (access rights).	❌ No
`405`	Method Not Allowed	The HTTP method you invoked is not supported on the corresponding API path. Please refer to the API Reference.	❌ No
`429`	Too Many Requests	You exceeded the API rate-limit.	✅ Yes (later)
`500`	Internal Server Error	Something unexpected happened. We were notified and will be investigating the problem. Please refer to our status page to know more.	✅ Yes (maybe)
`503`	Service Unavailable	The 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.

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

Strategy	Purpose	When needed
Handling errors (below)	Recover whenever an API request fails.	Always
Monitor webhooks	React 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."
    }
}

{
    "type": "https://datatracker.ietf.org/doc/html/rfc7235#section-3.1",
    "title": "Unauthorized",
    "status": 401,
    "instance": "https://example.ilucca.net/lucca-api/employees/1573"
}

{
    "type": "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.3",
    "title": "Forbidden",
    "status": 403,
    "instance": "https://example.ilucca.net/lucca-api/employees/1573"
}

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
    "title": "Not Found",
    "status": 404,
    "instance": "https://example.ilucca.net/lucca-api/employees/1573"
}

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.

Get Started

Using Lucca API

Webhooks

Resources

Error Handling

Problem Details

Common HTTP Status Codes

Errors due to limits being reached

Error Handling

Handling 4xx Errors

Handling Deprecation Warnings

Handling 5xx Errors

Browse Logs

​Problem Details

​Common HTTP Status Codes

Errors due to limits being reached

​Error Handling

​Handling 4xx Errors

​Handling Deprecation Warnings

​Handling 5xx Errors

​Browse Logs

Problem Details

Common HTTP Status Codes

Error Handling

Handling 4xx Errors

Handling Deprecation Warnings

Handling 5xx Errors

Browse Logs