Errors

When things go wrong, Churro tells you exactly what burned. Every error returns a structured JSON object with enough context to fix it fast.

Error Shape

JSON

{ "error": { "type": "invalid_request_error", "code": "missing_required_field", "message": "The 'product_id' field is required.", "param": "product_id", "request_id": "req_abc123xyz" } }

typeError category — what kind of mess we're dealing with.

codeMachine-readable code for programmatic handling.

messageHuman-readable explanation. We try to be helpful, not cryptic.

paramThe specific field that caused the issue, if applicable.

request_idInclude this in support requests — it's your receipt.

HTTP Status Codes

200OKGolden. Everything worked.

400Bad RequestSomething in the request doesn't look right.

401UnauthorizedMissing or invalid API key. No ticket, no churro.

403ForbiddenYour key doesn't have permission for this.

404Not FoundThat resource doesn't exist. Sold out.

429Rate LimitedSlow down — too many orders at once.

500Server ErrorSomething broke on our end. We're on it.

Error Types

authentication_error

Your API key is invalid, expired, or revoked. Time for a fresh one.

invalid_request_error

Bad parameters or missing required fields. Double-check the recipe.

rate_limit_error

Too many requests. The kitchen is backed up — retry after the Retry-After header.

api_error

Something unexpected on our servers. Rare, and automatically reported.

quota_exceeded_error

You've used all your API credits. Time to upgrade or top off.

Handling Errors

The SDK throws typed errors you can catch and handle gracefully. No uncooked exceptions.

TypeScript

import { Churro, ChurroError } from '@churro/sdk'; try { const quote = await churro.quote({ ... }); } catch (err) { if (err instanceof ChurroError) { console.error(err.type, err.message); if (err.type === 'rate_limit_error') { await sleep(err.retryAfter); } } }

Rate Limit Headers

Every response includes these headers so you know how many orders the kitchen can still take.

X-RateLimit-LimitMax requests per minute for your plan.

X-RateLimit-RemainingRequests left in the current window.

X-RateLimit-ResetUnix timestamp when the window resets.

Retry-AfterSeconds to wait before retrying (429 only).