Errors - Pawabase

When something goes wrong, Pawabase answers with an HTTP status and a body that says why. This page lists every shape you can receive, every error code, how the SDKs surface them, and what to do.

The four shapes of an error

Which shape you get depends on who refused the request.

1. The error envelope

Sent by the gateway (key, quota and rate-limit problems) and by the data API (an unknown filter field, a duplicate value).

{
  "error": "invalid_api_key",
  "message": "invalid API key",
  "request_id": "01JD9…",
  "hint": "Check the key in Settings → API keys.",
  "retry_after": 30,
  "details": { "…": "…" }
}

Field	Meaning
`error`	A stable code to branch on. Never match on `message`.
`message`	What went wrong, for a person.
`request_id`	Also sent as the `x-request-id` header. Quote it to support, and look it up in Activity.
`hint`	What to try next, when there is one.
`retry_after`	Seconds to wait, on `429` and `503`. Also sent as the `retry-after` header.
`details`	Structured extras: the offending columns, the limit that was hit.

2. A plain message

A refusal from a service endpoint, such as sign-in, is a bare JSON string: "Authentication required", "Not found".

3. A list of validation errors (422)

A request body that failed validation lists one entry per field:

[
  { "type": "missing", "loc": ["body", "email"], "msg": "Field required" },
  { "type": "string_type", "loc": ["body", "password"], "msg": "Input should be a valid string" }
]

loc is the path to the offending field and msg is readable. The SDKs turn these into per-field messages (see below).

4. A query problem

A bad query parameter, and framework refusals such as a wrong method, answer { "detail": … } where detail is a list like the one above, or a string.

The error codes

`error`	Status	Meaning and what to do
`missing_api_key`	401	No key was sent. Send it in the `apikey` header.
`invalid_api_key`	401	The key is unknown, revoked, expired or malformed, or doesn’t belong to the environment the request names (this key does not belong to environment …: pass the right `environment` to the client). Check it, or make a new one in Settings → API keys.
`key_service_unavailable`	503	Keys could not be checked just now. Retry shortly; the SDKs do.
`origin_not_allowed`	403	The key doesn’t allow requests from this browser origin. Add the site to Websites allowed to call it in Environment settings.
`forbidden`	403	The key lacks a scope, route or address for this request. See API keys.
`host_environment_mismatch`	403	The key belongs to a different environment than the address serves.
`rate_limit_exceeded`	429	The key’s or route’s rate limit was exceeded. Wait `retry_after` seconds.
`request_quota_exceeded`	429	Your plan’s monthly request quota is used up. See Plans and limits.
`bandwidth_quota_exceeded`	429	Your plan’s monthly bandwidth is used up.
`bad_request`	400	The request is well formed but can’t be served: an unknown field in `sort`, `filter` or `select`, or bad SQL. `message` names the field.
`unique_violation`	409	A value that must be unique already exists. `details` names the columns.
`constraint_violation`	422	The change breaks a database constraint, such as a missing parent record.
`payload_too_large`	413	The body is larger than your plan allows.
`method_not_allowed`	405	That method isn’t allowed on this path.
`database_unavailable`	503	The environment’s database could not be reached. Retry shortly.
`internal_error`	500	Something failed on the server. Quote `request_id`.
`not_found`	404	Nothing is served at that address.

Flows can also fail a run with their own HTTP status, code and message using the error block (error.raise).

What each status means

Status	Usually means	First thing to try
400	The request can’t be understood or names something that doesn’t exist	Read `message`
401	Missing or invalid key, or the person isn’t signed in or their token expired	Sign in again; the SDK refreshes tokens for you
403	Known caller, not allowed: an access rule refused it, or the key lacks a scope	Open the request in Activity and read the decision
404	No such record, file or route, or a rule hides it from this caller	Check the id and the caller’s access
405	Wrong method	Check the endpoint
409	A unique value is already used, or the record changed under you	Choose another value or reload
413	Body too large	Send less, or upload files with a signed URL
422	Input failed validation	Show the per-field messages
429	Too many requests, or a plan quota	Wait `retry_after`; check usage
5xx	A problem on the server or a dependency	Retry; quote the request id if it persists

A 404 can mean “not allowed to see it”. Pawabase doesn’t reveal that a record exists to someone who may not read it.

Errors in the SDKs

All errors extend one base type. Catch the specific ones you care about and let the rest bubble up.

TypeScript	Python	Status	Meaning
`AuthenticationError`	`AuthenticationError`	401	Not signed in, token expired, or wrong API key
`PermissionError`	`ForbiddenError`	403	Signed in, but a rule refuses this
`NotFoundError`	`NotFoundError`	404	No such record or file, or a rule hides it
`ConflictError`	`ConflictError`	409	A unique value is already used
`ValidationError`	`ValidationError`	400, 422	Invalid or missing input
`PayloadTooLargeError`		413	Body larger than allowed
`RateLimitError`	`RateLimitedError`	429	Too many requests
`ServerError`	`ServerError`	5xx	A problem on the server
`NetworkError`	`NetworkError`	none	The request never got an answer
`RealtimeError`	`RealtimeError`	none	A live channel was refused or closed
`ConfigError`	`ConfigError`	none	The client was set up wrongly

In Python, QuotaExceededError (a kind of ForbiddenError) means the plan’s limit is reached.

What an error carries

TypeScript	Python	Meaning
`status`	`status_code`	The HTTP status
`code`	`code`	The stable code, such as `not_found` or `rate_limited`
`message`	`message`	A readable description
`requestId`	`request_id`	Quote this when asking for help
`retryAfter`	`retry_after`	Seconds to wait, on 429 and 503
`policy`		The rule that refused, on 403, when known
`details`		Extra structured data

ValidationError also has issues, fieldError(field) and byField() for form messages.

import { ApiError, ValidationError, AuthenticationError } from "@pawabase/client";

try {
  await pawabase.from("profiles").create({ email: "nope" });
} catch (e) {
  if (e instanceof ValidationError) {
    console.log(e.byField());                 // { email: ["must be a valid email"] }
  } else if (e instanceof AuthenticationError) {
    window.location.assign("/login");          // signed out: send them to sign in
  } else if (e instanceof ApiError && e.is("rate_limited")) {
    console.log(`slow down: retry in ${e.retryAfter}s`);
  } else {
    console.error(e instanceof ApiError ? `${e.message} (request ${e.requestId})` : e);
  }
}

from pawabase import ValidationError, AuthenticationError, RateLimitedError, PawabaseError

try:
    pb.from_("profiles").create(email="nope")
except ValidationError as e:
    print(e.message)
except AuthenticationError:
    redirect_to_login()
except RateLimitedError as e:
    print("retry in", e.retry_after)
except PawabaseError as e:
    print(e.status_code, e.message, e.request_id)

curl -i "$URL/rest/v1/profiles" -H "apikey: bad"
# HTTP/1.1 401
# {"error":"invalid_api_key","message":"invalid API key","request_id":"…"}

Retries

The SDKs already retry rate limits (429), 502, 503, 504 and network failures, with short growing delays, and they honour retry_after. You see an error only if it keeps failing. Tune it with the retry option, or pass retry: false. Do not retry 400, 401 (after the SDK’s own refresh), 403, 404, 409 or 422: the same request will fail the same way. Fix the request first. When you retry a write, make it safe to repeat: use a unique key your own code controls, so a repeated request returns 409 instead of creating a second record.

Errors in other places

Where	How errors show
Flows	A failing block ends the run as failed. The run’s trace shows the block and message. See Flow runs.
Webhooks	A failed delivery is retried. See Webhook deliveries.
Agents	A run ends with status `failed` and an `error`, or stops `waiting`. See Run an agent.
AI models	Provider errors are returned in OpenAI’s error shape (`{"error": {"message", "type", "code"}}`). See Chat and streaming.
Realtime	A refused subscription or publish arrives as a `RealtimeError`. See Channels.

Contacting support

Include the request id (x-request-id), the time, the environment and what you expected. With the id, support (and you, in Activity) can see exactly what happened, including which rule refused a call.

​The four shapes of an error

​1. The error envelope

​2. A plain message

​3. A list of validation errors (422)

​4. A query problem

​The error codes

​What each status means

​Errors in the SDKs

​What an error carries

​Retries

​Errors in other places

​Contacting support

The four shapes of an error

1. The error envelope

2. A plain message

3. A list of validation errors (422)

4. A query problem

The error codes

What each status means

Errors in the SDKs

What an error carries

Retries

Errors in other places

Contacting support