Error Handling

The Lindris API uses conventional HTTP response codes to indicate the success or failure of API requests. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with our servers.

Common Status Codes

• 200 - OK. The request was successful, and the response body contains the requested data.
• 201 - Created. The request was successful and a resource was created.
• 400 - Bad Request. The request was unacceptable, often due to missing required parameters.
• 401 - Unauthorized. No valid API token provided or token has expired.
• 403 - Forbidden. The API token doesn't have permissions to perform the request.
• 404 - Not Found. The requested resource doesn't exist.
• 422 - Unprocessable Entity. The request was well-formed but was unable to be processed due to validation errors.
• 429 - Too Many Requests. Request was rejected due to rate limiting. See Rate Limits for more information.
• 500 - Internal Server Error. Something went wrong on our end.
• 503 - Service Unavailable. We're temporarily offline for maintenance.

Error Response

When an error occurs, the API will return a JSON response in the following format:

{
    "message": "The given data was invalid.",
    "errors": {
        "email": [
            "The email field is required when id is not present."
        ],
        "id": [
            "The id field is required when email is not present."
        ]
    },
    "code": "validation_error",
    "status_code": 422,
}

• message - A human-readable message providing a brief description of the error.
• errors - An object containing field-specific validation errors. This key is not always present, so check for its existence before accessing it.
• code - A machine-readable error code string.
• status_code - The HTTP status code of the response.

Validation Errors

For requests that fail validation, the errors object will contain field-specific error messages. Each field can have multiple error messages. For example:

{
    "message": "The given data was invalid.",
    "errors": {
        "status": [
            "The selected status is invalid."
        ],
        "tags.newTag": [
            "The tags.newTag field must be true or false."
        ],
        "email": [
            "emailAddress identifier is reserved for system use. Please choose a different one."
        ]
    },
    "code": "validation_error",
    "status_code": 422
}

Error Handling Best Practices

When working with the API, we recommend:

1. Always check the HTTP status code of the response.
2. For any non-200 responses, check the errors object for field-specific validation errors. This key is not always present, so check for its existence before accessing it.
3. Use the code field for programmatic error handling.
4. Display the message field to users when appropriate.
5. Log the entire error response in development for debugging.
6. For 429 responses, implement exponential backoff and respect the retry_after value. See Rate Limits for detailed guidance.