Troubleshooting

Start in Cockpit under Developers → Request logs. You’ll find the full request and response for every call there, so you can usually confirm what went wrong in one place.

Every response includes an Aleta-Request-Id. Log it, including for successful requests. It’s the first thing support will ask for.

Authentication and permissions

You see	Cause
401 missing_credentials	There’s no Authorization header, or it isn’t in the Bearer <token> format
401 invalid_access_token	The token is expired, revoked, or for the wrong environment. Tokens are short-lived, so fetch a new one instead of caching it for hours
403 insufficient_scope	The client doesn’t have the required scope. Check it in Cockpit → Developers → OAuth clients
403 environment_mismatch	An at_test_ token is being used against production data, or the other way around
403 ip_not_allowed	The caller’s IP address isn’t on the client’s allowlist
403 production_not_enabled	Production access hasn’t been enabled for your organization yet

404 on an endpoint that exists

There are two common causes, and the error tells you which one you’re dealing with.

404 not_found with no resource name means the route isn’t mounted. Routes are only available when the processor behind your program supports them.

For example, GET /v1/transactions returns 404 for a program whose processor doesn’t report transactions, even though the endpoint is included in the spec.

404 <resource>_not_found means the route is working, but the ID isn’t. Usually, the resource belongs to another organization or environment.

Something is refused with a 422

You see	Fix
program_not_provisioned	The program isn’t set up on this deployment. Contact your account contact
operation_unsupported	The operation isn’t available on this program’s processor
kyc_not_approved	Make sure the cardholder has an approved KYC outcome before issuing
identity_document_required	Set identity_document when creating the cardholder. It can’t be added later
address_required	Add an address with PATCH /v1/cardholders/{id}
kyc_identity_required	This program’s processor handles its own verification. Send identity on the attestation
currency_mismatch	The account currency and the request currency don’t match
card_invalid_state	The card is frozen or closed. Read the card first to check its current state
unsupported_country	The country isn’t enabled for the program

Duplicates and conflicts

You see	Cause
409 idempotency_key_reuse	The same Idempotency-Key was used with a different request body. Use a new key for the new request
409 idempotency_request_in_progress	The first request using that key hasn’t finished yet. Wait and retry with the same key
409 cardholder_already_exists	A cardholder with that reference already exists

Webhooks aren’t arriving

Check Developers → Webhook delivery logs first. The logs show whether we tried to deliver the event and what happened.

What the log shows	Cause
Nothing for that event	The endpoint isn’t subscribed to that event type, or it was disabled when the event happened
A transport error	Your host can’t be reached from the internet, or the TLS connection failed
signature does not match from your handler	Something parsed and re-serialized the request body. Verify the raw bytes instead
Repeated non-2xx	Your handler is failing. The response body is captured in the log
Endpoint marked disabled	There were 20 consecutive failures. Re-enable it, then reconcile the gap through the API. Nothing was queued while the endpoint was disabled

See retries, backoff and ordering for more detail.

Rate limits and upstream failures

429 rate_limited includes RateLimit-Reset, which tells you how many seconds to wait. Back off for that long instead of retrying immediately.

Limits apply per client and are also tracked per organization, so adding more clients won’t increase the limit.

502 processor_unavailable means the card processor is unavailable, not that there’s a problem with our API. It’s safe to retry with the same Idempotency-Key. The key prevents a retry from creating a second card or debit.

500 internal_error means something went wrong on our side. Send us the request_id when you contact support.

Related

• Error code catalog — every error code.
• Contacting support — what to include in a support ticket.