This article explains common API errors with 4xx client-side errors like 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), and 429 (Too Many Requests), and 5xx server-side errors such as 500, 502, 503, and 504. It advises checking inputs, credentials, permissions, and rate limits, using retries with exponential backoff, logging errors, and provides details to send for support investigation. It does not cover UI access or product specific troubleshooting hints.
To start, we're sorry that you're here diagnosing an API error instead of building the integration your insurance product workflows depends on. The Realytix team works to make API interactions reliable, but when a request fails, use the status code and response details below to identify the cause and get your requests working again.
Please see below possible errors and hints to resolve common issues that may arise. When making API calls, it's common to encounter errors, often indicated by status codes. Understanding these errors can help resolve issues quickly.
Client-Side Errors (4xx Status Codes)
400 Bad Request
This error occurs when the Product cannot process the request due to an invalid input, such as incorrect parameters. Please ensure all inputs meet the API's requirements.
Possible types are: EXTERNAL, RULEENGINE, TEST, VALIDATION, MIN, MAX, REQUIRED, TYPE, EVAL or PATTERN.
--> Studio Insights
401 Unauthorized
This status indicates that authentication has failed. It usually occurs when credentials are missing, are invalid, or have expired. In general, double-check that your access token and subscription key are correct and up-to-date.
-
Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription.
Double check within the API Developers portal and use a valid subscriptionKey. -
Access token is missing or invalid:
Eventually it is an application/client-id whitelisting in APIM. It could be solved by removing the configured IP-Whitelisting. -
Unauthorized access attempt: Insufficient permissions. (with traceId)
It could be a wrong tenant/product id combination, missing characters in the ID or spelling mistakes in the IDs. -
Authentication with oAuth failed. Unauthorized. (without traceId)
Often a token issue and could be potentially solved by "allow-listing" the client-id.
403 Forbidden
This error means the server understood the request but refuses to authorize it. It may happen if your access permissions are insufficient or if you're attempting an action not allowed for your role.
- without trace id: Most of the time an IP address issue and IP-Whitelisting need to be adjusted
- with trace id: Any other permission issue
404 Not Found
This error is returned when the requested resource does not exist. It may be due to an incorrect endpoint or an unavailable API feature. Verify that the URL and resource identifiers are accurate.
405 Method Not Allowed
This indicates that the HTTP method used (e.g., DELETE) is not supported for the requested resource. Check the API documentation to ensure you're using the correct method.
413 Request Entity Too Large
This error occurs when the size of the request exceeds the server's limits, often due to an overly large file upload. Reduce the size of your request or file to comply with the allowed limits. REALYTIX ZERO supports requests up to 2 MB.
429 Too Many Requests
This status is shown when the rate limit for API calls has been exceeded. To resolve this, reduce the frequency of requests or implement a retry mechanism after waiting for the specified time period.
Each API subscription has a maximum limit of 600 calls per minute. Plan your API usage accordingly to stay within this rate limit.
Server-Side Errors (5xx Status Codes)
Server-side errors indicate issues within the REALYTIX ZERO platform itself, often outside the product designer's control. Understanding these errors helps diagnose server-side issues effectively but since they are related to server performance or configuration, this is more a Realytix team action. The Realytix team is actively monitoring those errors. Here's an overview of common 5xx errors and how to handle them:
500 Internal Server Error
This error indicates that the server encountered an unexpected condition that prevented it from fulfilling the request. It’s a generic error, and usually retrying the request after some time can resolve it. If the issue persists, contact support for further assistance.
502 Bad Gateway
This occurs when the server, acting as a gateway or proxy, receives an invalid response from an upstream server. It typically suggests network or server configuration issues. Retrying the request or checking the server status may help.
503 Service Unavailable
This error means the server is temporarily unable to handle the request, often due to maintenance or overload. The best course of action is to wait and try again later. It's also advisable to check any server status updates.
504 Gateway Timeout
This status is returned when the server, acting as a gateway or proxy, does not receive a timely response from an upstream server. This might occur due to network delays or heavy load. Retrying the request or optimizing request parameters (e.g. reducing processing time) can sometimes mitigate this error.
507 Insufficient Storage
This error indicates that the server cannot store the representation needed to complete the request. It's rare but usually suggests that the server's storage capacity is full. Contact server support to resolve this issue.
Tips to Handle API Errors
Implement Error Handling Logic:
Always check the status code of API responses and handle errors appropriately in your application.
Use Retries and Exponential Backoff:
For transient errors, such as network issues, implementing retry logic with exponential backoff can help.
Log Errors for Debugging:
Log the errors with detailed information for troubleshooting and monitoring purposes.
In case you would like us to investigate errors or issues, please send us the following information so that we can easily start investigating:
- OAuth client ID
- RX0 meta information: Environment, Product ID, Tenant ID
- Time of your request
- Content of your API call request
- Content of your API call response
- TraceId (if available)
- Screenshots if applicable that could help us identifying the issue
Related Articles
Browser UI Sign-In and Access Errors
Product Error handling and Troubleshooting