Errors

How Syper reports failures and how to handle them.

Syper uses conventional HTTP status codes and returns a structured error body that tells you what went wrong and whether retrying can help.

Classes of error

Client errors (4xx)

The request is invalid, unauthenticated, forbidden, or conflicts with current state. Fix the request — retrying unchanged will fail again.

Rate limiting (429)

Too many requests. Back off and retry.

Server errors (5xx)

Something failed on Syper's side. Retry with the same idempotency key.

Declines

The request was valid but a financial rule prevented it — insufficient funds, a limit, a risk decision. Surface to the user; don't blindly retry.

Handling errors

• Branch on the machine-readable error code, not the human-readable message.
• Retry only errors that are safe to retry, and always with an idempotency key.
• Log the request identifier returned with each response — it lets support trace the request.

The full list of error codes lives in the Errors API reference.