Errors

Every error of the Baiyar API has the same shape and a stable code. Find what a code means and what to do about it.

Every error answers with a non-2xx HTTP status and the same JSON body. Handle it by error.code (stable), not by the text of error.detail (meant for people, may change).

{
  "error": {
    "type": "request_error",
    "code": "invalid_field",
    "detail": "Request does not pass validation.",
    "documentation_url": "https://docs.baiyar.com/resources/errors/invalid_field/",
    "errors": [{ "field": "amount", "message": "must be at least 1" }]
  },
  "meta": { "request_id": "req_…" }
}

error.type groups codes; error.code says exactly what happened.
error.errors appears for validation failures, one entry per field.
meta.request_id identifies the request: quote it when you contact us. It is also in every response.
A 429 and a 409 idempotency_in_progress carry Retry-After (seconds).

Request errors

The request or the state of the resource is the problem. Change something before you send it again.

Code	HTTP	Meaning
`invalid_field`	400	Request does not pass validation.
`invalid_request`	400	Request body is invalid.
`not_found`	404	Resource was not found.
`already_exists`	409	A resource with the same unique value already exists.
`invalid_state`	409	Resource is not in a valid state for this action.
`data_unreadable`	409	The stored data was sealed with a key this environment does not have, so it cannot be shown.
`version_conflict`	409	The resource changed since you loaded it. Reload and try again.
`limit_exceeded`	409	A usage limit has been reached.
`method_not_allowed`	405	This HTTP method is not allowed for this endpoint.
`unsupported_media_type`	415	Content-Type is not supported for this endpoint.
`request_body_too_large`	413	Request body is too large.
`payment_method_not_enabled`	422	This payment method is not enabled for this project.
`payment_rejected`	422	The payment could not be created with these values.
`webhook_endpoint_limit`	409	The limit of webhook endpoints was reached. Delete one before adding another.
`payment_link_unavailable`	404	This payment link is not available.
`payment_link_in_use`	409	This payment link is already being paid or was paid.
`payment_link_limit_reached`	409	This payment link has reached the number of payments it allows.
`checkout_session_invalid`	401	This checkout session is not valid. Open the payment link again.

Authentication errors

We could not tell who is calling. Check the credentials you send.

Code	HTTP	Meaning
`invalid_credentials`	401	Invalid email or password.
`invalid_current_password`	401	Invalid current password.
`session_required`	401	Authentication is required.
`invalid_two_factor_code`	401	Invalid or expired verification code.
`invalid_or_expired_token`	401	Invalid or expired token.
`invalid_api_key`	401	The API key is not valid.

Authorization errors

We know who you are, but this is not allowed for that key or account.

Code	HTTP	Meaning
`forbidden`	403	You are not allowed to perform this action.
`verification_required`	403	Additional verification is required before this action.
`insufficient_scope`	403	This API key does not have the permission this request needs.
`ip_not_allowed`	403	This API key cannot be used from this IP address.
`project_not_approved`	403	This project has not been approved for live yet.
`project_not_active`	403	This project is not active.

Rate limit errors

Too many requests. Slow down and retry after the delay.

Code	HTTP	Meaning
`rate_limited`	429	Too many requests. Please try again later.

Idempotency errors

Something is wrong with the Idempotency-Key of the request.

Code	HTTP	Meaning
`idempotency_key_reused`	409	This Idempotency-Key was used with a different request.
`idempotency_in_progress`	409	A request with this Idempotency-Key is still being processed.

API errors

Something went wrong on our side, or a provider did not answer. It is safe to retry a request that carries an Idempotency-Key.

Code	HTTP	Meaning
`provider_unavailable`	503	This payment method is not available right now.
`provider_not_configured`	503	This provider is not connected on this server: its credentials are not set.
`provider_unclear`	502	The payment provider did not give a clear answer. Check the payment before retrying.
`internal_error`	500	An unexpected error occurred.
`service_unavailable`	503	Service is temporarily unavailable.