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

A URI identifying the error type, in the form https://terminal.smartretry.com/errors/<reason_code>.

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 request signature is missing, invalid, or expired, or the API Secret is not active. See Authentication.
`403`	Forbidden	The API Secret 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. This happens when the same `Idempotency-Key` is reused with a different request body (`ROUTING/IDEMPOTENCY_CONFLICT`), or when another operation holds the lock on the same order or recurring series (`ROUTING/RESOURCE_LOCKED`).
`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. This happens when another request with the same `Idempotency-Key` is still in flight and the replay wait timed out (`ROUTING/RESOURCE_LOCKED`).
`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`, `403`, `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}/{order_id}/{transaction_id}`	`400`, `403`, `404`, `500`
Complete payer actions	`POST /v1/payments/status/{terminal_friendly_id}/{order_id}/{transaction_id}/payer-actions/{plan_id}/complete`	`400`, `403`, `404`, `409`, `500`, `503`

Reason codes

Reason code	Status	Description
`MISSING_TIMESTAMP`	401	The `x-timestamp` header is missing.
`MISSING_SIGNATURE`	401	The `x-signature` header is missing.
`INVALID_API_KEY`	401	No active API Secret exists for the terminal in the path, for example because it was revoked.
`TIMESTAMP_EXPIRED`	401	The `x-timestamp` value is more than 5 minutes from server time.
`INVALID_SIGNATURE`	401	The `x-signature` value does not match the signature SmartRetry computed.
`ROUTING/RECORD_NOT_FOUND`	404	The `terminal_friendly_id` in the path does not match any known terminal.
`ROUTING/TERMINAL_RESOURCE_ACCESS_DENIED`	403	The referenced resource (transaction, order, recurring series) belongs to a different terminal than your API Secret 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`	409	Another operation currently holds the lock on the same order or recurring series. SmartRetry does not wait. Retry after a short backoff.
`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.
`VALIDATION/INVALID_FIELD/CURRENCY`	400	The `currency` value is not a supported ISO 4217 currency code, or `VALIDATION/UNAUTHORIZED_CURRENCY` if it isn’t enabled for this terminal.
`VALIDATION/INVALID_FIELD/PAYMENT_CARD_NUMBER`	400	The card number failed the Luhn check or is not a recognised card format.
`VALIDATION/INVALID_FIELD/PAYMENT_CARD_EXPIRY_MONTH` / `..._EXPIRY_YEAR`	400	The card expiry date is missing, out of range, or in the past.
`VALIDATION/MISSING_FIELD`	400	A field required by this endpoint was not included in the request body. `context.field` is a JSON pointer to the missing field.
`VALIDATION/UNKNOWN_FIELD`	400	The request body included a field the schema does not accept. `context.field` is a JSON pointer to it.
`VALIDATION/INVALID_FIELD`	400	A field failed schema validation for a reason not covered above (wrong type, pattern, or range). `context.field` is a JSON pointer to it.
`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.

This is a curated shortlist of common codes. See Status reason codes for the full catalog, including all decline and processor-level reasons.

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://terminal.smartretry.com/errors/INVALID_SIGNATURE",
  "title": "Invalid Signature",
  "status": 401,
  "detail": "The x-signature header does not match the signature computed for this request.",
  "reason_code": "INVALID_SIGNATURE"
}

{
  "type": "https://terminal.smartretry.com/errors/VALIDATION/MISSING_FIELD",
  "title": "Validation Error",
  "status": 400,
  "detail": "The 'amount' field is required and must be a positive number in major currency units.",
  "instance": "/v1/payments/sale/ABC123",
  "reason_code": "VALIDATION/MISSING_FIELD",
  "context": {
    "field": "/amount"
  }
}

{
  "type": "https://terminal.smartretry.com/errors/VALIDATION/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/ORD8A3F2/TX8A3F2C",
  "reason_code": "VALIDATION/TRANSACTION_NOT_FOUND"
}

{
  "type": "https://terminal.smartretry.com/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"
}

{
  "type": "https://terminal.smartretry.com/errors/ROUTING/IDEMPOTENCY_CONFLICT",
  "title": "Conflict",
  "status": 409,
  "detail": "The Idempotency-Key was already used with a different request body.",
  "instance": "/v1/payments/sale/ABC123",
  "reason_code": "ROUTING/IDEMPOTENCY_CONFLICT"
}

{
  "type": "https://terminal.smartretry.com/errors/ROUTING/RESOURCE_LOCKED",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Another request with the same Idempotency-Key is still being processed. Retry shortly.",
  "instance": "/v1/payments/sale/ABC123",
  "reason_code": "ROUTING/RESOURCE_LOCKED"
}

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 - check the reason_code, then verify your x-timestamp and x-signature headers. See Authentication.
403 Forbidden - the API Secret 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.

Retryable conflicts

409 Conflict with ROUTING/RESOURCE_LOCKED - another operation holds the lock on the order or recurring series. Retry after a short backoff.

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

Statuses

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