Errors | border.bot API docs

border.bot API error format, every error code with its HTTP status, and which errors to retry.

Errors return JSON with a stable, machine-readable code, a message written for people, and sometimes details:

json

{
  "error": {
    "code": "insufficient_credits",
    "message": "This workspace needs 5 credits and has 2.",
    "details": { "required": 5, "balance": 2 }
  },
  "requestId": "0199c8d2-5b1e-7c3a-9f4e-2d6b8a1c3e5f"
}

Every response carries an X-Request-Id, and error bodies repeat it as requestId. It is a UUID (UUIDv7, lowercase); MCP tool results carry the same id in _meta["border.bot/requestId"]. Quote it when you contact support, or find the request with GET /v1/requests?requestId=… (older requests keep their req_… ids, which still match).

Codes#

Code	HTTP	Meaning
`invalid_input`	400	The request failed validation. The message names the field to fix.
`unauthorized`	401	The API key is missing, malformed or revoked.
`insufficient_credits`	402	The workspace balance is too low for this action. Top up in the dashboard.
`forbidden`	403	The key is valid but not allowed to perform this action (a key without the scope the endpoint needs: details.reason is missing_scope).
`not_found`	404	The resource or path doesn’t exist.
`conflict`	409	A request with the same idempotency key is still running, or the change clashes with existing data. Wait and retry.
`org_suspended`	403	The workspace is suspended. Contact support.
`payload_too_large`	413	The request body is over 10 MB. Link to a photo instead of sending it inline, or split a bulk run.
`version_retired`	410	The API version in the path has passed its sunset date. Move to the version the message names.
`action_disabled`	403	This action is temporarily switched off. Try again later.
`unsupported_country`	422	The destination isn’t covered for this action yet. The message says what is supported.
`rate_limited`	429	Too many requests in a short period. Back off and retry.
`upstream_error`	502	The engine couldn’t complete the request. Credits were refunded; retry.
`upstream_timeout`	504	The engine took too long. Credits were refunded; retry.
`internal`	500	Something went wrong on our side. Credits were refunded.

What to retry#

429, 502 and 504: retry with backoff and the same Idempotency-Key. Credits for a failed call are already refunded.
409 conflict on a repeated idempotency key: the first request is still running, so wait and retry.
Everything else: fix the request first. invalid_input names the field in its message and lists up to ten problems in details.issues.