Error Response Structure

All API errors are returned in JSON format with a standardized structure:

{  
  "message": "Error message here",
}   

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of requests. Here are the primary status codes you'll encounter:

200 OK

• Description: Request processed successfully
• Usage: Returned when API calls complete without errors

400 Bad Request

• Description: The request is invalid due to missing, incorrect, or malformed parameters
• Common Causes:
  • Missing required fields (identityNumber, tenantKey, etc.)
  • Invalid data format (incorrect date format, invalid ID number format)
  • Parameter validation failures

401 Unauthorized

• Description: Authentication failed or token is invalid
• Common Causes:
  • Missing Authorization header
  • Invalid or expired Bearer token
  • Incorrect tenant credentials

404 Not Found

• Description: The requested resource or endpoint does not exist
• Common Causes:
  • Incorrect API endpoint URL
  • Identity number not found in database
  • Refugee file number does not exist

406 Not Acceptable

• Description: The request cannot be processed due to content negotiation issues
• Common Causes:
  • Incorrect Content-Type header
  • Unsupported request format

429 Too Many Requests

• Description: Rate limit exceeded
• Common Causes:
  • Too many requests sent within the rate limit window
  • Concurrent request limits exceeded

500 Internal Server Error

• Description: An unexpected server error occurred
• Common Causes:
  • Server-side processing errors
  • Database connectivity issues
  • Temporary service unavailability

502 Bad Gateway

• Description: Server received an invalid response from upstream services
• Common Causes:
  • Temporary service disruption
  • Network connectivity issues