Skip to main content

​
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:
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.

​
Breaking changes

Primer commits to not introducing breaking changes in endpoints or API versions without also introducing a minor API version bump. You can expect endpoints that you’re using to not have breaking changes until you upgrade to another version. However, you should expect non-breaking or additive changes, and we encourage you to design your systems to protect against this possibility. Currently, non-breaking changes can happen inside the same minor API version, and breaking changes cannot. Primer considers breaking changes to be changes that can potentially break an integration. Breaking changes include:
  • removing an entire operation
  • removing or renaming a parameter
  • removing or renaming a response field
  • adding a new required parameter
  • making a previously optional parameter required
  • changing the type of a parameter or response field
  • removing enum values
  • adding a new validation rule to an existing parameter
  • changing authentication or authorization requirements
Primer considers non-breaking changes to be changes that should not break an integration, and that you should protect against. Additive changes include:
  • adding an operation
  • adding an optional parameter
  • adding an optional request header
  • adding a response field
  • adding a response header
  • adding values to existing enums
If, in exceptional circumstances, we do need to introduce a breaking change without bumping the API version, then we will ensure to communicate this ahead of any release, working closely with you to mitigate any possible impact. 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.