Errors

The SmartRetry API uses standard HTTP status codes and serializes documented failures using the shared error body below. Use reason_code as the machine-readable identifier and retain detail for diagnostics.

Error response structure

All error responses share this shape:

string

required

Identifies the error category.

string

required

A short, human-readable summary of the error.

integer

required

The HTTP status code for this response (e.g., 400, 401, 404).

string

required

A detailed description of what went wrong in this specific request. Use this field for debugging and logging.

string

Identifies the request associated with this occurrence when available.

string

required

A machine-readable code identifying the failure cause. Use this for programmatic error handling and branching logic.

object

Optional error-specific data. Its properties vary by error.

HTTP status codes

Status	Name	When it occurs
`200`	OK	The operation completed successfully or a submission was accepted for processing. Retrieve Transaction status for the current payment outcome.
`400`	Bad Request	The request body or parameters failed validation. A required field is missing, a value is the wrong type, or a parameter is out of range.
`401`	Unauthorized	The `x-api-key` header is missing or the key is invalid.
`403`	Forbidden	The API key is valid but does not have access to the requested terminal.
`404`	Not Found	The transaction, recurring plan, or terminal ID does not exist.
`409`	Conflict	The request conflicts with existing state. For idempotency, this happens when the same `Idempotency-Key` is reused with a different request body.
`422`	Unprocessable Entity	The request is structurally valid but was rejected by business logic - for example, attempting to capture an already-captured pre-auth.
`429`	Too Many Requests	Your integration has exceeded the rate limit. Back off and retry after the period indicated in the `Retry-After` response header.
`503`	Service Unavailable	The API could not complete the request right now. For idempotency, this can happen when another request with the same key is still in flight and the replay wait timed out.
`500`	Internal Server Error	An unexpected error occurred on the SmartRetry side. If this persists, check status.smartretry.com and contact support.

Status codes by operation

This matrix lists all non-success responses declared by each published operation. Authentication and rate-limiting guidance above is maintained separately and does not add undeclared responses to an operation.

Operation	Method and path	Declared error statuses
Initialize recurring	`POST /v1/payments/recurring/init/{terminal_friendly_id}`	`400`, `403`, `404`, `409`, `500`, `503`
Recurring status	`GET /v1/payments/recurring/status/{terminal_friendly_id}`	`400`, `404`, `500`
Cancel recurring	`POST /v1/payments/recurring/cancel/{terminal_friendly_id}`	`400`, `404`, `409`, `500`, `503`
Charge recurring	`POST /v1/payments/recurring/charge/{terminal_friendly_id}`	`400`, `403`, `404`, `409`, `422`, `500`, `503`
Update recurring	`PUT /v1/payments/recurring/update/{terminal_friendly_id}`	`400`, `404`, `409`, `422`, `500`
Future transaction status	`GET /v1/payments/recurring/future-transactions/status/{terminal_friendly_id}`	`400`, `404`, `500`
Update future transaction	`PUT /v1/payments/recurring/future-transactions/update/{terminal_friendly_id}`	`400`, `404`, `409`, `422`, `500`
Charge future transaction	`POST /v1/payments/recurring/future-transactions/charge/{terminal_friendly_id}`	`400`, `404`, `409`, `422`, `500`, `503`
Cancel future transaction	`POST /v1/payments/recurring/future-transactions/cancel/{terminal_friendly_id}`	`400`, `404`, `409`, `422`, `500`, `503`
Pre-authorization	`POST /v1/payments/preauth/{terminal_friendly_id}`	`400`, `403`, `404`, `409`, `422`, `500`, `503`
Sale	`POST /v1/payments/sale/{terminal_friendly_id}`	`400`, `403`, `404`, `409`, `422`, `500`, `503`
Refund	`POST /v1/payments/refund/{terminal_friendly_id}`	`400`, `403`, `404`, `409`, `422`, `500`, `503`
Void	`POST /v1/payments/void/{terminal_friendly_id}`	`400`, `403`, `404`, `409`, `422`, `500`, `503`
Capture	`POST /v1/payments/capture/{terminal_friendly_id}`	`400`, `403`, `404`, `409`, `422`, `500`, `503`
Transaction status	`GET /v1/payments/status/{terminal_friendly_id}/{transaction_id}`	`400`, `403`, `404`, `500`

Reason codes

Reason code	Status	Description
`INVALID_API_KEY`	401	The `x-api-key` header is missing, malformed, or the key has been revoked.
`TERMINAL_NOT_FOUND`	403 / 404	The `terminal_friendly_id` in the path does not match any terminal your key can access.
`VALIDATION/TRANSACTION_NOT_FOUND`	404	No transaction with the given ID exists on this terminal.
`VALIDATION/INVALID_IDEMPOTENCY_KEY`	400	The `Idempotency-Key` header is malformed, too long, or contains unsupported characters.
`ROUTING/IDEMPOTENCY_CONFLICT`	409	The `Idempotency-Key` value was reused with a different request body. Reuse the same key only for an exact retry of the original POST request.
`ROUTING/RESOURCE_LOCKED`	503	Another request using the same `Idempotency-Key` is still in flight and SmartRetry could not obtain the cached result before the wait timeout.
`VALIDATION/INVALID_AMOUNT`	400	The `amount` value is missing, zero, negative, or not a valid number in major currency units.
`INVALID_CURRENCY`	400	The `currency` value is not a supported ISO 4217 currency code.
`INVALID_CARD_NUMBER`	400	The card number failed the Luhn check or is not a recognised card format.
`INVALID_EXPIRY`	400	The card expiry date is missing, in the wrong format, or in the past.
`VALIDATION/MISSING_FIELD`	400	A field required by this endpoint was not included in the request body. The `context` object identifies the missing field.
`RATE_LIMIT_EXCEEDED`	429	Too many requests in a short window. Honour the `Retry-After` header before retrying.
`VALIDATION/RECURRING_NOT_FOUND`	404	No recurring plan with the given terminal and reference exists.

Example error responses

The values below illustrate the shared response shape. A specific detail, reason_code, or context value is not guaranteed unless the endpoint contract declares it.

{
  "type": "https://www.smartretry.com/docs/api-reference/errors#invalid-api-key",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The x-api-key header is missing or the provided key is invalid.",
  "reason_code": "INVALID_API_KEY",
  "context": {}
}

{
  "type": "https://www.smartretry.com/docs/api-reference/errors#missing-required-field",
  "title": "Bad Request",
  "status": 400,
  "detail": "The 'amount' field is required and must be a positive number in major currency units.",
  "reason_code": "VALIDATION/MISSING_FIELD",
  "context": {
    "field": "amount"
  }
}

{
  "type": "https://www.smartretry.com/docs/api-reference/errors#transaction-not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "No transaction with ID 'txn_001' was found on terminal 'ABC123'.",
  "instance": "/v1/payments/status/ABC123/txn_001",
  "reason_code": "VALIDATION/TRANSACTION_NOT_FOUND",
  "context": {
    "terminal_friendly_id": "ABC123",
    "transaction_id": "txn_001"
  }
}

{
  "type": "https://www.smartretry.com/docs/api-reference/errors#rate-limit-exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "You have exceeded the request rate limit. Please wait before retrying.",
  "reason_code": "RATE_LIMIT_EXCEEDED",
  "context": {
    "retry_after_seconds": 30
  }
}

{
  "type": "https://www.smartretry.com/docs/api-reference/errors#idempotency-conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "The Idempotency-Key was already used with a different request body.",
  "reason_code": "ROUTING/IDEMPOTENCY_CONFLICT",
  "context": {
    "idempotency_key": "sale-order-20260401-001"
  }
}

{
  "type": "https://www.smartretry.com/docs/api-reference/errors#resource-locked",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Another request with the same Idempotency-Key is still being processed. Retry shortly.",
  "reason_code": "ROUTING/RESOURCE_LOCKED",
  "context": {}
}

Handling errors in production

Use reason_code rather than detail or title for programmatic handling. Human-readable fields may change.

Retryable errors

500 Internal Server Error - retry with exponential backoff. Check status.smartretry.com if errors persist beyond a few minutes.
429 Too Many Requests - wait for the number of seconds in the Retry-After response header before retrying. Do not retry immediately.
503 Service Unavailable - if the reason code is ROUTING/RESOURCE_LOCKED, retry the same POST request shortly with the same Idempotency-Key.

Non-retryable errors

400 Bad Request - fix the request before retrying. Check the context.field value to identify which field is invalid.
401 Unauthorized - verify your API key is correct and present in the x-api-key header.
403 Forbidden - the key is valid but not authorized for this terminal. Check you are using the right terminal_friendly_id.
409 Conflict - if the reason code is ROUTING/IDEMPOTENCY_CONFLICT, do not retry with the same key and a different body. Generate a new Idempotency-Key for a new operation.

Transaction outcomes A successful submission response confirms that the operation was accepted for processing. Use the Transaction status operation to retrieve the current payment outcome.

Log the full error response body for every non-2xx status, including instance when present. This makes it significantly faster to diagnose issues with SmartRetry support.

Overview

Payments

Recurring

Future Transactions

Error response structure

HTTP status codes

Status codes by operation

Reason codes

Example error responses

Handling errors in production

​Error response structure

​HTTP status codes

​Status codes by operation

​Reason codes

​Example error responses

​Handling errors in production

Error response structure

HTTP status codes

Status codes by operation

Reason codes

Example error responses

Handling errors in production