Error codes

Error codes provide stable, programmatic identifiers for specific failure conditions.

Use these codes to implement conditional logic in your integration.

Structure

Error codes are returned in the code field of the error object.

{
  "type": "card_error",
  "code": "card_declined",
  "decline_code": "insufficient_funds",
  "message": "Your card has insufficient funds.",
  "trace_id": "trc_123"
}

Categories

Invalid request errors

Errors caused by invalid input or request structure.

Examples:

• parameter_invalid
• missing_required_param
• amount_too_large

Recommended handling:

• Do not retry
• Fix the request data
• Display validation errors to the user

Authentication errors

Errors caused by missing or invalid credentials.

Examples:

• authentication_invalid — the Authorization header is malformed or uses an unsupported format
• authentication_required — the endpoint requires credentials and no supported credential was provided
• token_invalid — the provided access token or API key is invalid
• token_expired — the provided access token has expired

Recommended handling:

• Verify credentials
• Do not retry without fixing authentication
• Compare the masked credential shown in the error message with the credential your integration intended to send

Authorization errors

Errors caused by account context or permission checks after authentication succeeds.

Examples:

• account_required — the request requires an account context; provide the Paypercut-Account header
• account_invalid — the authenticated principal cannot access the selected account, or the account does not exist
• more_permissions_required — the provided credential does not have the required permission for this endpoint
• permission_denied — the authenticated principal is not allowed to perform the requested operation

Recommended handling:

• Send the Paypercut-Account header when acting on a connected account; X-Paypercut-Account is accepted as an alias
• Verify that the credential belongs to the expected environment and account
• Grant the required permission before retrying
• Do not infer account existence from account_invalid; the response is intentionally ambiguous

{
  "type": "invalid_request_error",
  "code": "authentication_required",
  "doc_url": "https://docs.paypercut.io/developer-resources/error-codes",
  "message": "Authentication is required for this endpoint.",
  "trace_id": "trc_123"
}

{
  "type": "invalid_request_error",
  "code": "token_invalid",
  "doc_url": "https://docs.paypercut.io/developer-resources/error-codes",
  "message": "The provided access token 'sk_test_...dsadas' is invalid.",
  "trace_id": "trc_123"
}

{
  "type": "invalid_request_error",
  "code": "account_required",
  "doc_url": "https://docs.paypercut.io/developer-resources/error-codes",
  "message": "This endpoint requires an account context. Provide the Paypercut-Account or X-Paypercut-Account header.",
  "trace_id": "trc_123"
}

{
  "type": "invalid_request_error",
  "code": "more_permissions_required",
  "doc_url": "https://docs.paypercut.io/developer-resources/error-codes",
  "message": "The provided credential 'sk_test_...abcdef' does not have the required permissions for this endpoint.",
  "trace_id": "trc_123"
}

Card errors

Errors caused by card or issuer behavior.

Examples:

• card_declined
• expired_card
• incorrect_number

Recommended handling:

• Use decline_code and advice_code
• Prompt the customer for action if needed

Processing errors

Errors caused by temporary processing issues.

Examples:

• processing_error
• issuer_unavailable

Recommended handling:

• Retry later
• Do not retry immediately in a tight loop

Rate limiting errors

Errors caused by exceeding request limits.

Examples:

• rate_limit_exceeded

Recommended handling:

• Back off and retry later
• Implement exponential backoff

Handling strategy

Best practices

• Treat error codes as stable integration contracts
• Avoid parsing error messages programmatically
• Combine code with other fields such as decline_code
• Keep retry logic explicit and controlled

Related pages

• Error handling
• Error object
• Declines