Skip to main content

API responses

HTTP response codes​

Getpaid API uses standard HTTP response codes to indicate the success or failure of an API request. It's important to distinguish between API-level success (HTTP status) and business-level outcomes (resource status):

  • 2xx range indicates the API request was successfully processed. The response body contains the requested resource or operation result. Note that a successful API response may include a resource in a failure or pending state (e.g., a declined payment). The resource's status and reason fields provide details about the business outcome. See status reasons for further details about its usage.
  • 3xx range indicates a redirection.
  • 4xx range indicates an error with the request itself, such as missing required fields, invalid parameters, authentication failures, or insufficient permissions. The response body includes details about the error as described in the error responses section.
  • 5xx range indicates a server error. These errors are typically temporary and requests can be retried with exponential backoff.

Error responses​

Errors in the 4xx range can include more details to help handle the error programmatically or report the error back to the user, such as missing required fields or validation problem (e.g., an email field that doesn't contain a valid email value). The type field is a link that points to the documentation for the error. The response body follows the RFC 7807 - Problem Details for HTTP APIs standard.

404 - Not Found​

This error happens when the entity you are requesting does not exist or it has been deleted.

{
  "type": "https://docs.getpaid.io/integration/api/responses#404---not-found",
  "title": "Not Found",
  "status": 404
}

409 - Conflict​

When the request cannot be completed due to the current state of the target resource, then the API will return an error with 409.

{
  "type": "https://docs.getpaid.io/integration/api/responses#409---conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "Request cannot be completed due to the current state of the server",
}

422 - Invalid Parameters​

When a request contains an invalid value the API will return an error with 422 status code and a body as:

{
  "type": "https://docs.getpaid.io/integration/api/responses#422---invalid-parameters",
  "title": "Invalid Parameters",
  "status": 422,
  "detail": "The request was invalid",
  "errors": {
    "field": ["required"]
  }
}

You will need to change the provided values to valid options in order to make the request succeed.