Responses and Errors#

Response codes#

Code	Status	Description
`200`	OK	Request succeeded.
`201`	Created	Resource created. The URI of the new resource is in the Location header.
`204`	No Content	Request succeeded with no response body.
`400`	Bad Request	Malformed request syntax. The response body contains details.
`401`	Unauthorized	Missing or invalid Authorization header, or the user has been disabled.
`403`	Forbidden	Valid credentials but insufficient permissions for this resource.
`404`	Not Found	Resource not found or not accessible to the authenticated user.
`405`	Method Not Allowed	HTTP verb not permitted. PATCH is not supported — use PUT.
`406`	Not Acceptable	Accept header content type not supported by this endpoint.
`409`	Conflict	Resource already exists.
`410`	Gone	Resource existed but has been removed.
`415`	Unsupported Media Type	Content-Type not accepted. See the error for supported types.
`422`	Unprocessable Entity	POST/PUT body was structurally valid but contained invalid data.
`426`	Upgrade Required	Request was made over HTTP — upgrade to HTTPS.
`429`	Too Many Requests	Rate limit exceeded. Check response headers for reset timing.
`500`	Internal Server Error	Server-side error. Retry, and report to support with the request_id if it persists.
`504`	Gateway Timeout	Request timed out. Retry, and report with request_id if it persists.

Error structure#

Every error response includes:

Field	Description
`type`	One of `gocardless`, `invalid_api_usage`, `invalid_state`, `validation_failed`
`code`	The HTTP status code
`message`	A short human-readable description
`documentation_url`	Link to the relevant docs section
`request_id`	Unique ID — include this when contacting support
`errors`	Array of specific errors (see below)

For validation_failed errors, each item in errors has a field and message. For all other types, each item has a reason and message.

Error types#

gocardless — Internal errors

These errors occurred within GoCardless while processing your request. Retry where indicated; report persistent issues to support with the request_id.

Reason	Description
`internal_server_error`	An internal error occurred. Report to support with `request_id`.
`request_timed_out`	Request did not complete in time. Retry, report if persistent.
`query_timed_out`	Database query timed out, possibly due to complexity. Retry with different parameters.

invalid_api_usage — Request errors

Errors caused by how the request was constructed — invalid URL, missing headers, authentication problems, or bad syntax.

Reason	Description
`invalid_type`	JSON was incorrectly typed or contained unknown parameters.
`path_not_found`	URL path not recognised. Check spelling and formatting.
`resource_not_found`	The ID in the request was not found.
`link_not_found`	A `link[resource]` ID was not found.
`unauthorized`	Credentials not recognised.
`forbidden`	Authenticated but no permission to access this resource.
`feature_disabled`	Feature not enabled on your account. Contact support to enable.
`not_acceptable`	`Accept` header content type not supported.
`request_entity_too_large`	Request body too large.
`unsupported_media_type`	Use `application/json` for `Content-Type` and `Accept`.
`rate_limit_exceeded`	Rate limit reached. Check headers for reset time.
`access_token_not_found`	No token found with the specified ID.
`access_token_not_active`	Token has been disabled.
`access_token_revoked`	Token has been revoked by the user.
`missing_authorization_header`	No `Authorization` header included.
`invalid_authorization_header`	`Authorization` header was malformed.
`insufficient_permissions`	Token doesn't have the required scope.
`insufficient_permissions_continue_on_dashboard`	Action can only be performed from the GoCardless dashboard.
`method_not_allowed`	HTTP verb not permitted. Use `PUT` instead of `PATCH`.
`bad_request`	Request syntax was incorrect.
`idempotency_key_too_long`	Idempotency key exceeded 128 characters.
`invalid_document_structure`	JSON was not structured correctly. Parameters must be nested under the resource name.
`invalid_content_type`	Missing or unsupported `Content-Type` header on a `POST`/`PUT`.
`tls_required`	API only accessible over HTTPS.
`missing_version_header`	No `GoCardless-Version` header included.
`version_not_found`	Specified version does not exist.
`invalid_filters`	Filter combination not allowed for this endpoint.
`request_body_not_allowed`	Request body not supported for this HTTP method — use query parameters.
`customer_data_removed`	Customer has been removed and can no longer be returned.
`payout_items_data_archived`	Payout items older than 6 months have been archived. Contact support for access.

invalid_state — State errors

The action is invalid given the current state of the resource. Inform the end user — do not allow them to retry.

Reason	Description
`cancellation_failed`	Resource was not in a cancellable state (already cancelled, failed, or too late in submission).
`retry_failed`	Payment could not be retried.
`disable_failed`	Bank account is already disabled.
`mandate_is_inactive`	Payment could not be created — mandate is cancelled, failed, or expired.
`mandate_replaced`	Mandate has been replaced. Check `links[new_mandate]` in the error or on the mandate itself.
`bank_account_disabled`	Mandate could not be created — linked customer bank account is disabled.
`mandate_not_inactive`	Mandate could not be reinstated — it is already active or being submitted.
`refund_is_unreachable`	Refund could not be created — it would not reach the target bank account.
`refund_payment_invalid_state`	Payment must be `confirmed` or `paid_out` before it can be refunded.
`total_amount_confirmation_invalid`	Total amount refunded does not match the confirmation value.
`number_of_refunds_exceeded`	Maximum of 5 refunds per payment already reached.
`idempotent_creation_conflict`	A resource already exists for the supplied idempotency key.
`customer_bank_account_token_used`	Bank account token has already been used.
`billing_request_must_be_ready_to_fulfil`	Billing request has outstanding required actions. Check the `actions` array.

validation_failed — Validation errors

Request parameters were invalid. Prompt the user to correct their input.

Reason	Description
`bank_account_exists`	Bank account already exists. The existing account is referenced in `links[customer_bank_account]` or `links[creditor_bank_account]` in the error response.
`available_refund_amount_insufficient`	Creditor balance is insufficient to cover the refund. The available amount is in `metadata.available_refund_amount`.

Individual field validation errors are returned in the errors array with a field, message, and request_pointer indicating the exact failing field.

Example error responses#

POST https://api.gocardless.com/customer_bank_accounts HTTP/1.1
Content-Type: application/json
{
  "customer_bank_accounts": {
    "account_number": "55779911",
    "branch_code": "I'm not a sort code",
    "account_holder_name": "Frank Osborne",
    "country_code": "GB",
    "links": { "customer": "CU123" }
  }
}
 
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
  "error": {
    "documentation_url": "/docs/api-reference/responses-and-errors#validation-failed",
    "message": "Validation failed",
    "type": "validation_failed",
    "code": 422,
    "request_id": "dd50eaaf-8213-48fe-90d6-5466872efbc4",
    "errors": [
      {
        "message": "must be a number",
        "field": "branch_code",
        "request_pointer": "/customer_bank_accounts/branch_code"
      },
      {
        "message": "is the wrong length (should be 8 characters)",
        "field": "branch_code",
        "request_pointer": "/customer_bank_accounts/branch_code"
      }
    ]
  }
}

POST https://api.gocardless.com/customer_bank_accounts HTTP/1.1
Content-Type: application/json
{
  "customer_bank_accounts": {
    "account_number": "55779911",
    "branch_code": "200000",
    "account_holder_name": "Frank Osborne",
    "country_code": "GB",
    "links": { "customer": "CU123" }
  }
}
 
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error": {
    "message": "Invalid document structure",
    "documentation_url": "/docs/api-reference/responses-and-errors#invalid-api-usage",
    "type": "invalid_api_usage",
    "request_id": "bd271b37-a2f5-47c8-b461-040dfe0e9cb1",
    "code": 400,
    "errors": [
      {
        "reason": "invalid_document_structure",
        "message": "Invalid document structure"
      }
    ]
  }
}

POST https://api.gocardless.com/creditor_bank_accounts HTTP/1.1
Content-Type: application/json
{
  "creditor_bank_accounts": {
    "account_number": "55779911",
    "branch_code": "200000",
    "country_code": "GB",
    "set_as_default_payout_account": true,
    "account_holder_name": "Nude Wines",
    "links": { "creditor": "CR123" }
  }
}
 
HTTP/1.1 409 Conflict
Content-Type: application/json
{
  "error": {
    "message": "Bank account already exists",
    "documentation_url": "/docs/api-reference/responses-and-errors#validation-failed",
    "type": "validation_failed",
    "request_id": "bd271b37-a2f5-47c8-b461-040dfe0e9cb1",
    "code": 409,
    "errors": [
      {
        "reason": "bank_account_exists",
        "message": "Bank account already exists",
        "links": { "creditor_bank_account": "BA123" }
      }
    ]
  }
}

What's next#

Making Requests

Authentication, headers, versioning, and how to structure every API call.

Learn more

Events

Subscribe to asynchronous events to be notified when payments fail, succeed, or change state.

Learn more