Error Reference

Every error response the CodeSpar API returns has the same shape:

{
  "error": "invalid_request",
  "message": "Missing required field: amount",
  "status": 400,
  "request_id": "req_a1b2c3d4"
}

• error — stable machine-readable code. Safe to branch on in your code.
• message — human-readable explanation. Surface to users with caution (may contain details you do not want to leak).
• status — HTTP status code.
• request_id — include in support tickets; lets us jump straight to your trace in the ledger.

This page is the canonical list. Each API reference page (/docs/api/*) also lists the errors specific to its surface.

4xx — client errors

400 — invalid_request

The request body or query parameters are malformed or missing required fields. The message field names the specific issue.

Common causes

• Missing a required field (e.g. amount on codespar_pay)
• Value out of range (e.g. amount: -100)
• Wrong type (e.g. amount: "100" when a number is expected)
• Malformed JSON body

Fix — validate against the endpoint's request schema before sending. The SDK's Zod schemas catch most of these at compile time.

400 — slug_invalid

Only on project creation. The slug contains disallowed characters, exceeds 64 chars, or is empty.

Fix — use lowercase alphanumeric + _ + -, max 64 chars.

400 — slug_reserved

Only on project creation. You tried to use default as a slug; it is reserved for the auto-created default project per organization.

401 — unauthorized

The API key is missing, malformed, or revoked.

Common causes

• No Authorization: Bearer ... header
• Key does not start with csk_live_ or csk_test_
• Key was rotated and the old one revoked
• Wrong environment (using csk_test_ in production or vice-versa)

Fix — verify the key in the dashboard (Settings → API Keys) and confirm it is active.

403 — forbidden

The API key is valid but lacks the scope required for this operation.

Common causes

• A read-only key calling a mutation endpoint
• A project-scoped key trying to access a different project
• Key scopes were narrowed and a call outside the new scope

Fix — check the key's scopes in the dashboard. Create a new key with the required scopes if needed.

404 — not_found

The resource does not exist or is not accessible to the authenticated organization.

Common causes

• Session ID for a closed or expired session
• Project ID from a different organization
• Server ID that is not in the catalog
• Trigger or delivery ID that was already deleted

Fix — verify the ID format (ses_<16>, prj_<16>, trg_<16>, dlv_<8>). Sessions expire after 30 minutes of inactivity; create a new one.

409 — slug_conflict

Only on project creation/update. Another project in the organization already uses this slug.

409 — webhook_url_conflict

Only on trigger creation. Another active trigger in the same project already subscribes the same URL to the same event. Use a different URL or update the existing trigger instead of creating a duplicate.

422 — needs_connection

A tool call hit a server that requires user-level OAuth, but the user has not connected it yet. The response includes a connect_url — send it to the user in conversation, and they connect. Subsequent tool calls use the stored credentials.

See Authentication > Connect Links.

422 — provider_unavailable

The selected provider returned an error that the router considers non-retriable (config issue, permanent rejection). Your agent can retry with an explicit provider field to route to a different one.

Not to be confused with provider_error (below) which is retriable.

429 — rate_limited

You hit a rate limit. The response includes Retry-After (seconds) and X-RateLimit-Reset (Unix epoch).

Common causes

• Rate limit for your tier exceeded — see Servers API rate limits
• Trigger-management endpoints have their own lower limit

Fix — respect Retry-After. Exponential backoff with jitter is the canonical pattern. If you hit limits constantly, consider the Enterprise tier which raises the ceiling.

429 — quota_exceeded

Historical — this error existed on the pre-pivot tiered model. The current per-settled-transaction model has no monthly quota. If you see this on the current API, please open a support ticket with request_id.

5xx — server errors

500 — internal_error

Something went wrong on our side. Retry with exponential backoff. If it persists, the request_id in the response body lets us jump straight to your trace.

502 — provider_error

The downstream provider returned a 5xx or an unexpected response. This is retriable — CodeSpar did not permanently fail the call, the provider's service is degraded.

Fix — retry with backoff. If sustained, consider passing provider explicitly to route around the degraded one.

503 — service_unavailable

CodeSpar is in the middle of a deployment, or a specific provider integration is temporarily down. Rare. Retry-After gives the expected recovery window.

504 — gateway_timeout

The provider did not respond within CodeSpar's upstream timeout (30 seconds). Most frequent on fiscal surfaces during SEFAZ peaks.

Fix — retry; if the operation is sensitive (NF-e, payout), check the provider's own dashboard before assuming the call did not go through.

SDK-level errors

The TypeScript and Python SDKs throw typed errors that wrap the HTTP responses:

See SDK Reference for the full type shapes.

Debugging

Every error includes a request_id. In the dashboard, search the Logs page for that ID to see the full trace: every upstream call, its response body, and timings.

For production support: open an issue at github.com/codespar/codespar with the request_id, timestamp, and expected behavior. See Debugging for the full bug-report template.

Next steps