Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.smartretry.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

The SmartRetry API uses standard HTTP status codes and returns a consistent error body on every failure. Parse the reason_code field for programmatic error handling - it identifies the specific failure cause regardless of which endpoint you called.

​
Error response structure

All error responses share this shape:
​
type
string
required
A URI reference that identifies the error type. Points to documentation for the specific problem category.
​
title
string
required
A short, human-readable summary of the error. Does not change between occurrences of the same error type.
​
status
integer
required
The HTTP status code for this response (e.g., 400, 401, 404).
​
detail
string
required
A detailed description of what went wrong in this specific request. Use this field for debugging and logging.
​
instance
string
A URI that identifies this specific occurrence of the error. Include this in support requests when available.
​
reason_code
string
required
A machine-readable code identifying the failure cause. Use this for programmatic error handling and branching logic.
​
context
object
Additional structured data about the error, such as which field failed validation or the conflicting transaction ID. Contents vary by error type.

​
HTTP status codes

StatusNameWhen it occurs
200OKRequest succeeded. For payment responses, also check the accepted field - a 200 with "accepted": false means the transaction was declined.
400Bad RequestThe request body or parameters failed validation. A required field is missing, a value is the wrong type, or a parameter is out of range.
401UnauthorizedThe x-api-key header is missing or the key is invalid.
403ForbiddenThe API key is valid but does not have access to the requested terminal.
404Not FoundThe transaction, recurring plan, or terminal ID does not exist.
409ConflictThe request conflicts with existing state. For idempotency, this happens when the same Idempotency-Key is reused with a different request body.
422Unprocessable EntityThe request is structurally valid but was rejected by business logic - for example, attempting to capture an already-captured pre-auth.
429Too Many RequestsYour integration has exceeded the rate limit. Back off and retry after the period indicated in the Retry-After response header.
503Service UnavailableThe 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.
500Internal Server ErrorAn unexpected error occurred on the SmartRetry side. If this persists, check status.smartretry.com and contact support.

​
Reason codes

Reason codeStatusDescription
INVALID_API_KEY401The x-api-key header is missing, malformed, or the key has been revoked.
TERMINAL_NOT_FOUND403 / 404The terminal_friendly_id in the path does not match any terminal your key can access.
TRANSACTION_NOT_FOUND404No transaction with the given ID exists on this terminal.
INVALID_IDEMPOTENCY_KEY400The Idempotency-Key header is malformed, too long, or contains unsupported characters.
IDEMPOTENCY_CONFLICT409The Idempotency-Key value was reused with a different request body. Reuse the same key only for an exact retry of the original POST request.
RESOURCE_LOCKED503Another request using the same Idempotency-Key is still in flight and SmartRetry could not obtain the cached result before the wait timeout.
INVALID_AMOUNT400The amount value is missing, zero, negative, or not a valid number in major currency units.
INVALID_CURRENCY400The currency value is not a supported ISO 4217 currency code.
INVALID_CARD_NUMBER400The card number failed the Luhn check or is not a recognised card format.
INVALID_EXPIRY400The card expiry date is missing, in the wrong format, or in the past.
MISSING_REQUIRED_FIELD400A field required by this endpoint was not included in the request body. The context object identifies the missing field.
RATE_LIMIT_EXCEEDED429Too many requests in a short window. Honour the Retry-After header before retrying.
RECURRING_NOT_FOUND404No recurring plan with the given terminal and reference exists.

​
Example error responses

{
  "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": {}
}

​
Handling errors in production

Always branch on reason_code, not on detail or title. The human-readable fields may change; reason_code values are stable across API versions.
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 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 IDEMPOTENCY_CONFLICT, do not retry with the same key and a different body. Generate a new Idempotency-Key for a new operation.
Declined transactions A declined transaction returns 200 OK with "accepted": false in the response body - this is not an error response. Do not confuse payment declines with API errors. Log the transaction status and handle the decline according to your retry strategy.
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.