Errors

Every error has this JSON body, whatever format you asked for, except the 503 a restarting server sends, listed in the table below:

404 Not Found

{
  "error": {
    "code": "not_found",
    "message": "Prism not found"
  }
}

Branch on the status and code. The message is for people. A validation message names the paths that failed and never repeats a value you sent. Unknown fields lists the keys you sent.

A failed result is not an error. It answers 502 with the result itself, as Errors and retries shows.

Every error

Status and code	message	What to do
400 validation_failed	Invalid request: <path>: <problem>	Fix the named path. Several problems are joined with ; .
400 validation_failed	Missing fields: subject	Send every field key of the prism version.
400 validation_failed	Unknown fields: body	Send only the field keys of the prism version.
400 validation_failed	Request too large: about 27100 tokens of fields, context and the longest question, the limit is 26000	Shorten the fields or the call's context. See Limits.
400 bad_request	Malformed request	The body is not valid JSON, or has a JSON Content-Type and no body.
401 unauthorized	Authentication required	Send Authorization: Bearer <key>.
401 unauthorized	Invalid API key	The key is unknown, revoked or not a Prismlet key. Create a key in the app.
404 not_found	Prism not found	No prism with that slug or id in this account, or it is archived.
404 not_found	Prism version not found	The version you pinned does not exist.
404 not_found	Result not found	No result with that id in this account.
404 not_found	This prism is archived, so it cannot answer.	A retry of a result whose prism is archived. Archived prisms answer nothing.
404 not_found	Route not found	Check the path and method. A browser's CORS preflight gets this too.
409 conflict	This idempotency key was already used for another prism.	Use a different key for this prism.
409 conflict	Only a failed result can be retried.	The result succeeded. Read it instead.
409 conflict	This result was already retried as <id>.	Read the named result, and retry that one if it failed too.
413 bad_request	Malformed request	The body is over 1 MiB.
415 bad_request	Malformed request	Send the body as application/json. On POST /v1/prisms/{prism}/results a text/plain body answers 400 instead.
500 internal_error	Internal server error	A bug on our side. Retry with a pause. With an idempotency key the repeat is safe.
503, no code	Service Unavailable	A server is restarting and took nothing. Retry with a pause. The body is {"error":"Service Unavailable","message":"Service Unavailable","statusCode":503}.

A 4xx error saves nothing. It never reaches the model either, with one exception, because the result is saved in a second step after the model answers: when two first calls with the same key race on different prisms, the one that loses answers 409 after it was sent. A key revoked while the model is answering still gets that call's result, and its next call answers 401.

Validation messages

An Invalid request message lists each failing path with the problem. The server's own messages:

Request	message
Both fields and text, or neither	Invalid request: fields: send either fields or text
A field over 100,000 characters	Invalid request: fields.text: String must contain at most 100000 character(s)
A field value that is not a string	Invalid request: fields.subject: Expected string, received number
version that is not a whole number	Invalid request: version: Expected integer, received float
version over 2147483647	Invalid request: version: Number must be less than or equal to 2147483647
idempotency_key over 200 characters	Invalid request: idempotency_key: String must contain at most 200 character(s)
A NUL or unpaired surrogate character in any string	Invalid request: fields.text: must not contain NUL or unpaired surrogate characters
An unknown format	Invalid request: format: Expected 'json' | 'raw' | 'csv' | 'tsv' | 'jsonl'
A result id that is not a UUID	Invalid request: result_id: Invalid uuid

Keys the API doesn't know are ignored, not rejected, so a misspelled optional key such as idempotencyKey does nothing.

The order of checks

When a request has several problems, the first check that fails decides the answer. For POST /v1/prisms/{prism}/results:

1. The body is parsed, then the path, format and body are validated: 400, 413 or 415.
2. The API key: 401.
3. The prism: 404.
4. The idempotency key: 409. A stored result that succeeded comes back and the call stops here. One that failed is retried with its stored fields and version, so steps 5 and 6 are skipped, but the size estimate still runs.
5. The version: 404.
6. The field keys, then the size estimate: 400.
7. The model: 200 or 502.

A request with a bad body and no key answers 400, not 401. A repeat of an idempotency key returns the stored result, or retries it with its stored fields and version, so the version and fields in the body don't matter.

For POST /v1/results/{result_id}/retry the order is the body, which must be absent, valid JSON or plain text, and is ignored (400, 413 or 415), then the path and format (400), the key (401), the result (404), whether it failed and whether it was retried (409), whether its prism is archived (404), the size estimate (400), then the model. GET /v1/results/{result_id} stops after the result and answers 200.