# Responses and Errors Source: https://docs.gocardless.com/docs/api-reference/responses-and-errors # 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 > **Info: Handle each type differently** > `gocardless` → alert your dev team or contact support directly. `invalid_api_usage` → alert your > dev team. `invalid_state` → inform the end user, do not allow retry. `validation_failed` → prompt > the user to correct their input. ### gocardless — Internal errors These errors occurred within GoCardless while processing your request. Retry where indicated; report persistent issues to [support](mailto:support@gocardless.com) 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 ```http POST https://api.gocardless.com/customer_bank_accounts HTTP/1.1 Content-Type: application/json } } HTTP/1.1 422 Unprocessable Entity Content-Type: application/json , ] } } ``` ```http POST https://api.gocardless.com/customer_bank_accounts HTTP/1.1 Content-Type: application/json } } HTTP/1.1 400 Bad Request Content-Type: application/json ] } } ``` ```http POST https://api.gocardless.com/creditor_bank_accounts HTTP/1.1 Content-Type: application/json } } HTTP/1.1 409 Conflict Content-Type: application/json } ] } } ``` ## What's next #### [Making Requests](/docs/api-reference/making-requests) Authentication, headers, versioning, and how to structure every API call. #### [Events](/docs/api-reference/events/payments) Subscribe to asynchronous events to be notified when payments fail, succeed, or change state.