API Reference

Errors

Pineprompt uses standard HTTP status codes together with JSON error bodies. Every error response your client may receive will follow one of the two shapes documented below.

Status codes

The status codes you may encounter when calling the Pineprompt API are summarized in the table below.

Field	Type	Description
200 OK	success	The request succeeded. The response body contains the requested resource or collection.
201 Created	success	A new resource was created. The response body contains the resource as it now exists.
204 No Content	success	The request succeeded but there is no body to return. Typically returned by delete operations.
400 Bad Request	error	A required header is missing, typically `Pineprompt-Project-Id` on a project-scoped endpoint.
401 Unauthorized	error	No bearer token was provided. You should send a valid API key in the `Authorization` header.
402 Payment Required	error	The organization does not have a usable subscription. Resolve in the billing dashboard.
403 Forbidden	error	The API key is valid but does not carry the required ability for the endpoint.
404 Not Found	error	The resource does not exist, or it exists but is outside the active organization or project.
422 Unprocessable Entity	error	The request body or query failed validation. Errors are returned field by field.
429 Too Many Requests	error	The rate limit has been exceeded. See Rate limits for guidance on how to back off.
500 Internal Server Error	error	Something went wrong on our side. You may safely retry idempotent reads after a short backoff.

The standard error shape

Most error responses return a single message field describing what went wrong:

{
  "message": "Missing ability: monitors:write"
}

Field	Type	Description
message	string	A human-readable description of what went wrong.

The validation error shape

A 422 response includes a per-field errors bag alongside the top-level message:

{
  "message": "The country field must be 2 characters. (and 1 more error)",
  "errors": {
    "country": [
      "The country field must be 2 characters."
    ],
    "models.0": [
      "ChatGPT does not support country 'ZZ'."
    ]
  }
}

Each key inside errors is a dot-path matching the input field, and each value is an array, so a single field may carry multiple rule violations.

Field	Type	Description
message	string	A human-readable summary of the first validation failure, with a count of any further failures.
errors	object<string, string[]>	A map keyed by the dot-path of each failing field, where every value is an array of one or more messages for that field.

Common pitfalls

404 instead of 403 for cross-tenant lookups. If a resource exists but belongs to a different organization or project, Pineprompt will return 404 rather than 403 to avoid leaking whether the resource exists at all.
PUT requires the full body. Update endpoints use PUT semantics, so every field must be present, even on update. A missing field will return 422.