The JAVIS API follows a consistent JSON error structure to help developers diagnose and resolve issues quickly. This section outlines common errors, their meanings, and best practices for handling them.

🔗 Standard Error Response Format

All error responses follow this JSON structure:

{
  "status": "error",
  "error": {
    "code": 400,
    "message": "Invalid request parameters.",
    "details": "The 'orderId' field is required."
  }
}

status → Indicates an error (error)
error.code → HTTP status code
error.message → Human-readable description of the error
error.details → Additional information for debugging (optional)

📡 Common HTTP Errors & Status Codes

Status Code	Meaning	Description
400	Bad Request	The request is malformed or missing required fields.
401	Unauthorized	The request lacks valid authentication credentials.
403	Forbidden	The user does not have permission to access this resource.
404	Not Found	The requested resource does not exist.
409	Conflict	The request conflicts with the current state of the resource.
422	Unprocessable Entity	The request was valid, but the server could not process it.
429	Too Many Requests	The client has exceeded the API rate limits.
500	Internal Server Error	A server-side error occurred. Try again later.
504	Gateway Timeout	The request took too long to process. Retry the request.

⏳ Handling Rate Limits (`429 Too Many Requests`)

If you exceed the rate limit, the API returns:

{
  "status": "error",
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. Try again after 30 seconds."
  }
}

🔄 Retry Strategy: Exponential Backoff

To avoid hitting rate limits repeatedly, implement exponential backoff:

Wait 1 second, retry.
If it fails, wait 2 seconds, retry.
If it still fails, wait 4 seconds, retry.
Continue doubling wait time (e.g., 8s, 16s) up to 5 retries.

🔥 Handling Server & Timeout Errors (`500`, `504`)

If a server-side error occurs (500 Internal Server Error, 504 Gateway Timeout), follow these best practices:

✅ Retry the request using exponential backoff.
✅ If retries fail multiple times, contact support.

🛠 Troubleshooting & Support

If you encounter persistent issues:

✅ Check the error message and HTTP status code.
✅ Ensure your request follows the API specification. ✅ Refer to the API documentation for required fields. ✅ Contact support if issues persist.

📧 Support Email: care@javis.ai