Detailed Error Guide for API Integration

1. AUTHORIZATION_MISSING

• HTTP Status Code: 401 Unauthorized
• Description: The request is missing the Authorization header or API key.
• Usage: This error occurs when a valid API key or token is not provided.
• Resolution:
  1. Add the Authorization header to your request.
  2. Ensure your API key or token is correctly configured.

Example JSON Response:

{
  "error": {
    "status": "error",
    "error_code": "AUTHORIZATION_MISSING",
    "http_status_code": 401,
    "details": ["Authorization header or API key is missing."],
    "message": "Authorization token is missing from the request."
  }
}

2. AUTHORIZATION_INVALID

• HTTP Status Code: 401 Unauthorized
• Description: The provided token or API key is invalid or expired.
• Usage: This error occurs when the token is incorrectly formatted or no longer valid.
• Resolution:
  1. Check the validity of your API key.
  2. Regenerate the token if it has expired.

Example JSON Response:

{
  "error": {
    "status": "error",
    "error_code": "AUTHORIZATION_INVALID",
    "http_status_code": 401,
    "details": ["The provided authorization token or API key is invalid."],
    "message": "Invalid API key or token."
  }
}

3. UNAUTHORIZED

• HTTP Status Code: 403 Forbidden
• Description: The user is authenticated but lacks permission to access the requested resource.
• Usage: Occurs when the user does not have the required role or permission.
• Resolution:
  1. Verify user roles and permissions.
  2. Contact the API provider for access.

Example JSON Response:

{
  "error": {
    "status": "error",
    "error_code": "UNAUTHORIZED",
    "http_status_code": 403,
    "details": ["You do not have permission to access this resource."],
    "message": "Access is forbidden for this resource."
  }
}

4. VALIDATION_ERROR

• HTTP Status Code: 422 Unprocessable Entity
• Description: The input data does not meet the API's validation requirements.
• Usage: Occurs when parameters are missing, incorrectly formatted, or invalid.
• Resolution:
  1. Verify input data matches the API documentation.
  2. Fix parameter formatting errors.

Example JSON Response:

{
  "error": {
    "status": "error",
    "error_code": "VALIDATION_ERROR",
    "http_status_code": 422,
    "details": ["Invalid data in the request."],
    "message": "The provided data fails validation rules."
  }
}

5. API_LIMIT_EXCEEDED

• HTTP Status Code: 429 Too Many Requests or 403 Forbidden
• Description: The API usage rate or quota limit has been exceeded.
• Usage: Occurs when requests exceed the allowed limit within a given time.
• Resolution:
  1. Reduce the frequency of requests.
  2. Contact the API provider to request a higher limit.

Example JSON Response:

{
  "error": {
    "status": "error",
    "error_code": "API_LIMIT_EXCEEDED",
    "http_status_code": 429,
    "details": ["The rate limit for API requests has been exceeded."],
    "message": "Too many requests made in a short time."
  }
}

6. RESOURCE_NOT_FOUND

• HTTP Status Code: 404 Not Found
• Description: The requested resource or endpoint is not found.
• Usage: Occurs when an invalid URL or resource identifier is used.
• Resolution:
  1. Double-check the endpoint URL.
  2. Ensure resource IDs are correct.

Example JSON Response:

{
  "error": {
    "status": "error",
    "error_code": "RESOURCE_NOT_FOUND",
    "http_status_code": 404,
    "details": ["The requested resource does not exist."],
    "message": "Resource not found."
  }
}

7. SERVER_ERROR

• HTTP Status Code: 500 Internal Server Error
• Description: An unexpected error occurred on the server side.
• Usage: Usually a temporary issue with the API server.
• Resolution:
  1. Retry the request after some time.
  2. Report the issue to the API support team if it persists.

Example JSON Response:

{
  "error": {
    "status": "error",
    "error_code": "SERVER_ERROR",
    "http_status_code": 500,
    "details": ["An internal server error occurred."],
    "message": "Internal Server Error. Please try again later."
  }
}

8. METHOD_NOT_ALLOWED

• HTTP Status Code: 405 Method Not Allowed
• Description: The HTTP method (e.g., POST, GET) is not allowed for the endpoint.
• Usage: Occurs when the request uses an unsupported HTTP method.
• Resolution:
  1. Refer to the API documentation for allowed methods.
  2. Use the correct HTTP method (e.g., GET instead of POST).

Example JSON Response:

{
  "error": {
    "status": "error",
    "error_code": "METHOD_NOT_ALLOWED",
    "http_status_code": 405,
    "details": ["HTTP method not supported for this route."],
    "message": "Invalid HTTP method."
  }
}

Conclusion

Understanding and handling error responses is crucial for effective API integration. Always log error responses and resolutions for debugging and improving user experience. For persistent issues, reach out to the API support team for assistance. Use the provided JSON examples to develop robust error-handling mechanisms in your application.