Error Handling

The Inshuwa API uses standard HTTP response status codes to indicate whether a request succeeded or failed.

Response Format

All error responses return a JSON body:

{
  "status": 400,
  "message": "Validation failed",
  "errors": {
    "firstName": ["The firstName field is required."],
    "phoneNumber": ["The phoneNumber field is required."]
  }
}

Client Error Responses (4xx)

Code	Name	Description
400	Bad Request	The request was malformed or missing required fields
401	Unauthorized	Missing or invalid API key
403	Forbidden	You do not have permission to access this resource
404	Not Found	The requested resource does not exist
409	Conflict	The request conflicts with existing data (e.g., duplicate registration number)
422	Unprocessable Entity	The request was well-formed but contains semantic errors
429	Too Many Requests	Rate limit exceeded

Server Error Responses (5xx)

Code	Name	Description
500	Internal Server Error	An unexpected error occurred on the server
502	Bad Gateway	The server received an invalid response from an upstream service
503	Service Unavailable	The server is temporarily unavailable
504	Gateway Timeout	The upstream service did not respond in time

Best Practices

• Always check the HTTP status code before processing the response body
• Implement retry logic with exponential backoff for 5xx errors
• Log error responses including the message field for debugging
• For 401 errors, verify your API key is correct and included in the header