Server-to-Server API Response Codes & Errors

Follow
Avatar
Jared Ornstead
Updated

Response Codes

When integrating with Singular's API, all responses return HTTP 200 status codes, requiring validation of the response body's 'status' field to determine success ('ok') or failure ('error').

The response payload includes a 'reason' field providing detailed error information when status is 'error'.

Recommendations

  • Implement an exponential backoff retry mechanism with configurable maximum attempts, excluding non-retryable errors such as invalid parameters.
  • Maintain request order during retries to ensure data consistency.
  • For proper debugging and monitoring, log all failed requests including original parameters, error messages, device identifiers, and timestamps. Track retry attempts and implement a notification system for critical failures. The error response format follows a consistent JSON structure with status and reason fields.

This comprehensive error handling strategy ensures robust API integration while maintaining data accuracy and providing clear visibility into potential issues.

 

Success

The following identifies a successful API response to a request.

HTTP Response 
200 - ok

The 200 - ok without any error or reason in the response body means the request was sent to the queue for processing.

 

Response: 
{
    "status": "ok"
}

Errors

The following identifies error messages that the API could return in a response to a request.

HTTP Response 
200 - error

The 200 - error response code with 'reason' of "missing argument: {param}".

This error will only occur for specific parameters and not all required parameters.

If parameter is missing or the value is missing, you may receive a missing argument error. The error should be resolved and the request resent.

 

Response: 
{
    "status": "error",
    "reason": "missing argument: a"
}
 
200 - error

The 200 - error response code with 'reason' of "invalid platform: {platform}". This means the platform value is not valid.

The error should be resolved and the request resent.

 

Response: 
{
    "status": "error",
    "reason": "invalid platform: Desktop"
}
 
200 - error

The 200 - error response code with 'reason' of "no device ID supplied". The device identifier was not included on the request.

The error should be resolved and the request resent.

 

Response: 
{
    "status": "error",
    "reason": "no device ID supplied"
}
 
200 - error

The 200 - error response code with 'reason' of "platform: {platform} should have an {identifier} param". The error means the specified platform does not have the correct device identifier.

The error should be resolved and the request resent.

 

Response: 
{
    "status": "error",
    "reason": "platform: PC should have an sdid param"
}
 
XXX

Requests should be retried if you do not receive a 200 - ok.