The Osigu API uses standard HTTP status codes to indicate the success or failure of API requests. In addition to status codes, we provide detailed error messages to help you troubleshoot and resolve issues effectively.

Sometimes, the error might be transient (temporary), and retrying the request could succeed. However, in other cases, the error is due to a business rule or invalid input, and retrying the request will not resolve the issue. Below are guidelines for when to retry or not retry requests.

Common HTTP Status Codes and Retry Guidelines

200 OK: The request was successful. No need to retry.
201 Created: The resource was successfully created. No need to retry.
204 No Content: The request was successful, but no content is returned. No need to retry.

4xx Client Errors

Errors in the 4xx range indicate that something is wrong with the client's request. In most cases, retrying these requests will not resolve the problem unless the issue is corrected first.

400 Bad Request: The request was invalid due to malformed syntax or invalid parameters.
Do not retry. Review and correct the input before resubmitting the request.
401 Unauthorized: The request is missing authentication credentials or invalid credentials.
Do not retry. Ensure that your authentication token is correct and has not expired.
403 Forbidden: The request was understood, but the client does not have permission to access the resource.
Do not retry. Ensure that your user or token has the appropriate permissions for the requested operation.
404 Not Found: The requested resource could not be found.
Do not retry unless you’re sure the resource exists. Check the resource ID or URL, and ensure the resource has been created.
409 Conflict: The request conflicts with the current state of the resource (e.g., trying to create a duplicate invoice).
Do not retry. Check the conflict details in the response and modify your request accordingly (e.g., ensure unique invoice numbers).
422 Unprocessable Entity: The request was well-formed, but the server could not process it due to business rule violations.
Do not retry. Check the error message for details about the business rule violation (e.g., invoice eligibility for cashout requests).

5xx Server Errors

Errors in the 5xx range indicate that something went wrong on the server. These errors are typically transient, meaning the server was temporarily unable to process the request. In these cases, retrying the request may be appropriate.

500 Internal Server Error: A generic error indicating something went wrong on the server.
Retry after a delay. If the error persists, contact Osigu support.
502 Bad Gateway: The server, while acting as a gateway, received an invalid response from the upstream server.
Retry after a delay. This error is usually temporary.
503 Service Unavailable: The server is currently unable to handle the request, often due to temporary overload or maintenance.
Retry after a delay. This error should resolve itself once the service is available again.
504 Gateway Timeout: The server, while acting as a gateway, did not receive a timely response from the upstream server.
Retry after a delay. If the issue persists, consider contacting Osigu support.

Recommended Retry Strategy

For errors in the 5xx range, it’s generally recommended to implement an exponential backoff strategy. This prevents the server from being overwhelmed and gives it time to recover from temporary issues. Here’s an example retry strategy:

Initial retry: After 1 second.
Second retry: After 2 seconds.
Third retry: After 4 seconds.
Subsequent retries: Continue to double the delay, up to a reasonable limit (e.g., 32 seconds).

For non-transient errors (4xx errors), ensure that the problem is fixed before retrying the request. Retrying without fixing the issue will result in repeated failures.

Format

Error Response Format: When an error occurs, the API returns a response with additional details:

{
  "code": "DUPLICATE_INVOICE",
  "message": "An invoice with this number already exists for the provider."
}