API Responses

Status Codes

The following table summarizes the HTTP response codes you may receive from the Primer REST API.

Error Responses

Primer uses conventional HTTP response codes to indicate the success or failure of an API request. HTTP codes in the 2XX range indicate a successful request, whereas codes in the 4XX range indicate a failed request usually due to invalid inputs or operations.

The format of the payload for all errors is common. When an unsuccessful request occurs, you will receive a payload in the following format:

1
{
2
  "error": {
3
    "errorId": "AnErrorId",
4
    "description": "A human description of the error.",
5
    "diagnosticsId": "1234567890",
6
    "validationErrors": []
7
  }
8
}

All error payloads will be comprised of a unique errorId which you can use to identify the error, a human description description, and a diagnosticsId that you can quote when contacting the support team (support@primer.io). In case of a badly formed request, Primer will also return additional validationErrors.

Payment Status

As the payments are created, processed, and finalised, they go through a number of states that you will get as an API response, through webhook notifications, and in the Dashboard. These states are used across all processors, as processor specific states are mapped to these. An additional message, in the field processorMessage, from the processor may also be included that details the reason for the state, primarily on failure states.

Don’t hesitate to reach out with any questions or feedback. You can email Primer directly at support@primer.io, or contact your Primer account manager.