🛑Errors

The Leatherback API uses standard HTTP status codes to indicate the success or failure of requests. All responses include a status field and detailed error information to help you diagnose and resolve issues quickly.

Error Response Format

All error responses follow a consistent JSON structure with a top-level status field:

JSON

{
  "isSuccess": false,
  "title": "Access Denied!",
  "status": 401,
  "detail": "Access Denied! You do not have the necessary permissions to perform this action. Please contact the Leatherback team for assistance.",
  "traceId": "00-b5aa368c66bff0279d7162dbc184a747-c971865180e32372-00"
}

Response Fields

Field	Type	Description
isSuccess	boolean	A high-level flag indicating if the request was successful. Always false for errors.
title	string	A short, human-readable summary of the error type.
status	integer	The HTTP status code (e.g., 400, 401, 404, 500).
detail	string	A granular explanation of the error and suggested resolution steps.
traceId	string	A unique identifier for the request, essential for debugging with our support team.

HTTP Status Codes

The API returns these status codes:

2xx Success

Code	Meaning	Description
200	OK	Request succeeded (status: true)

4xx Client Errors

Code	Meaning	Description
400	Bad Request	Invalid request parameters or malformed JSON
401	Unauthorized	Missing or invalid authentication credentials
404	Not Found	Resource does not exist

5xx Server Errors

Code	Meaning	Description
500	Internal Server Error	Unexpected server error occurred
503	Service Unavailable	Service temporarily unavailable

Error Handling Best Practices

1. Always Handle Errors Explicitly

Check both the HTTP status code and the status field in the response. Handle errors based on the machine-readable code field.

2. Log Error Details

Include the error code, message, status, and request context in your logs:

3. Implement Retry Logic

Retry transient errors (500, 503) with exponential backoff. Don't retry client errors (4xx):

4. Validate Before Sending

Reduce 400 errors by validating data client-side before making requests:

Need Help?

If you encounter an error you can't resolve:

1. Check the code field against this documentation for the specific error
2. Review the errors array for detailed validation failures
3. Verify you're using the correct API key prefix for your environment
4. Test your request using Test Keys (sk_test_) before production
5. Contact support