Errors

The pd4castr API uses conventional HTTP status codes to signal the outcome of a request. 2xx responses mean success, 4xx responses mean the request was rejected (most often because of a missing or expired token, an unknown identifier, or a malformed body), and 5xx responses mean the service couldn’t complete the request.

Every error endpoint returns the same JSON shape, so you can write a single error handler that works across the API.

Response shape

A failed request always returns a JSON body with three fields:

{
  "statusCode": 404,
  "message": "Model not found",
  "error": "Not Found"
}

Field	Type	Description
`statusCode`	`number`	The HTTP status code, repeated in the body so you can log it without inspecting the response object.
`message`	`string`	A human-readable description of what went wrong. Safe to surface to operators; not localised.
`error`	`string`	A short, stable label that you can switch on programmatically. See Error labels.

Status codes

Code	Meaning	When you’ll see it
`400`	Bad Request	The request body or query string failed validation. The token endpoint returns this when `grant_type` is missing or set to anything other than `client_credentials`.
`401`	Unauthorized	The `Authorization` header is missing, the bearer token is invalid or expired, or the client credentials sent to `/v1/auth/token` were rejected.
`404`	Not Found	The model, model group, or run id you referenced doesn’t exist, or your organisation doesn’t have access to it.
`502`	Bad Gateway	The authorization server was temporarily unreachable, so no fresh token could be issued. Transient; safe to retry.

Error labels

Some errors carry a stable machine-readable label in the error field. Switch on the label rather than parsing message, which is intended for humans and may change.

Label	Status	Meaning
`Bad Request`	`400`	Generic validation failure. Inspect `message` for the specific field.
`Unauthorized`	`401`	The bearer token is missing, malformed, or expired. Request a new token from `/v1/auth/token` and retry.
`invalid_client`	`401`	Returned only by `/v1/auth/token` when your `client_id` or `client_secret` are wrong or have been revoked. Don’t retry; re-check your credentials or contact support.
`Not Found`	`404`	The referenced resource doesn’t exist. Don’t retry with the same id.
`Bad Gateway`	`502`	The authorization server was unreachable. Retry after a short back-off.

Handling errors

A pragmatic error handler covers four cases:

400 — Fix the request and don’t retry. The message field tells you which input was rejected.
401 with error: "Unauthorized" — Refresh your bearer token by calling /v1/auth/token again, then retry the original request once. If the second attempt still fails, the token endpoint itself is rejecting your credentials; treat it as invalid_client.
401 with error: "invalid_client" — Stop. Your client credentials are wrong or revoked. Don’t retry.
404 — The resource doesn’t exist. Surface the failure to the caller rather than retrying.
502 — The authorization server is briefly unreachable. Retry with exponential back-off starting at one second. Most callers recover within a few seconds.

For everything outside this list (network timeouts, dropped connections, unexpected 5xx), retry with exponential back-off and cap the total attempts.

Next steps

Authentication — exchange your client credentials for a bearer token.
Quick Start — end-to-end TypeScript example covering the full request lifecycle.