Error Handling

In the course of using the Justt API, you may encounter various error responses. These responses are designed to provide valuable information to help you identify and resolve issues. Errors are represented in the following format

Example:

{  
  "error": "Invalid API key",  
  "message": "The provided API key is invalid or expired",  
  "errorId": "eeb14651-71d6-4653-8ee3-498a20d1f77c"  
}

error_id

a unique identifier you can provide to our support for a better troubleshooting process

Error Types:

Authorization Errors (HTTP 401/403)
These errors occur when authentication or authorization issues are encountered.

Rejection messages for Unauthorized 401:

Message (401)	Reason
Authorization error. Your account has more than one merchant. Set the reference account header: https://developers.justt.ai/docs/reference-accounts	`reference-account-id` header missing when the account has more than one merchant or on a group (multi-merchant) key, which always needs it
Authorization error. Your account dont have permission to access the refer account	`reference-account-id` header is something the API key cannot reach, examples: an account key given a uuid not on the account a single-merchant key given anything but its own merchant a group key given a merchant outside the group
Authorization error. Your credential is scoped to merchants and cannot be used on account level endpoints.	A merchant-scoped or group key used on an account-level endpoints, example: GET/POST /v1/merchants, GET /v1/merchants/:merchantUuid
Authorization error. Your account has no merchant to act on. Attach a merchant to the account, or use a merchant-scoped credential.	Account key whose account has no merchant attached, so there is nothing for the header to name
Authorization error. Missing token header in request see https://developers.justt.ai/docs/authentication	No `Authorization` header
Authorization error. Invalid token format.	`Authorization` header present but the token is malformed or empty
Authorization error. Your credential is invalid.	The value does not authenticate. It could be expired or revoked.

Request Validation Errors (HTTP 400)
Errors resulting from invalid or incomplete request parameters.

Resource Not Found (HTTP 404)
Occurs when attempting to access a non-existent resource.

Payload Too Large (HTTP 413)
The payload size exceeds the maximum limit. Reduce your payload size and try again.

Rate Limit Exceeded (HTTP 429)
Triggered when rate limits for API endpoints are exceeded.

Server Errors (HTTP 5XX)
These errors indicate issues on the server side.

Common Error Messages:

"Invalid API Key": The provided API key is invalid or has expired.

"Resource Not Found": The requested resource does not exist.

"Rate Limit Exceeded": You've exceeded the rate limit for this API endpoint.

"Internal Server Error": An unexpected server error has occurred.

Troubleshooting:

When you encounter an error, review the error message and error type for specific information on the issue. Make sure to double-check your request, including the API key, and verify that you are within rate limits. If the problem persists, reach out to our support team for assistance.

Error Handling and Retry Strategies

HTTP 5XX Errors

When encountering 5XX series errors (server-side errors), implementing a retry strategy is recommended. These errors typically indicate temporary issues that may resolve on subsequent attempts.