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 or trying to modify does not exist or 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. This can also happen when there are concurrent processes affecting the same resource.

{
  "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"]
  }
}

In some cases, you may also receive an additional node containing metadata related to the error. This metadata will contain information to help resolve the issue that caused the request to fail:

{
  "type": "https://docs.getpaid.io/integration/api/responses#422---invalid-parameters",
  "title": "Invalid Parameters",
  "status": 422,
  "detail": "The request was invalid",
  "errors": {
    "enum_field": ["invalid_option"]
  },
  "errors_metadata": {
    "enum_field": {
      "invalid_option": {
        "allowed_options": ["option1", "option2"]
      }
    }
  }
}

For the request to succeed, you will need to send a new request modifying the information that produced the error in the original request.

503 - Server Unavailable​

In extraordinary circumstances, some of our services might not be fully available due to downstream services experiencing temporary issues. In such cases, you might receive a 503 error and should try again later using an exponential backoff strategy:

{
  "type": "https://docs.getpaid.io/integration/api/responses#503---server-unavailable",
  "title": "Server Unavailable",
  "status": 503,
  "detail": "Request cannot be completed due to downstream services being unavailable",
}