Errors

What a failed call returns in the model API and the management API, and every error code AI uses.

In the model API

Chat and model calls answer failures in OpenAI’s shape, so OpenAI’s SDKs raise them as errors with the message and code:

{
  "error": {
    "message": "The project has used the 100000 AI units its plan allows this month.",
    "type": "unit_limit_reached",
    "code": "unit_limit_reached",
    "param": null
  },
  "requestId": "01m3c081dbf3j55x7hsa7wc1yj"
}

code is the contract. Branch on it. type holds the same code.
param names the field at fault, when there is one. The message lists every field that is wrong.
message is a sentence for a person and may be reworded at any time.
When a failure is worth trying again, the answer has a Retry-After header with the seconds to wait.

In the management API

Usage and limits calls answer failures with a problem document, like every other Digitospace API. See Problems.

{
  "type": "https://docs.digitospace.com/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "1 field(s) are invalid",
  "instance": "/v1/projects/01k5ztq3jb9y2a1m9v2xw8e0ha/limits",
  "requestId": "01m3c081dbf3j55x7hsa7wc1yj",
  "retryable": false,
  "issues": [
    {
      "field": "unitsPerMonth",
      "code": "out_of_range",
      "message": "Use a whole number from 0 to 1,000,000,000,000, or null to use the plan's"
    }
  ]
}

When the failure is on our side, the answer does not say why. Quote its requestId when you contact us, and we can find what happened.

Codes

Code	Status	Retryable	When
`already_exists`	409	no	Something with that identity already exists
`answer_cut_off`	400	no	The answer reached its token limit before its JSON finished; allow more output tokens
`answer_invalid`	502	yes	The model did not answer with JSON that matches the schema; the answer still counts toward your AI units
`challenge_failed`	403	yes	A web page’s challenge was wrong, used, or expired; ask for a new one
`conflict`	409	no	The request clashes with the current state
`context_too_long`	422	no	The messages and `max_tokens` do not fit in the model’s context
`forbidden`	403	no	The key or your access does not allow this in the project
`internal`	500	no	Something went wrong on our side
`invalid_request`	400	no	The request is malformed, such as a field we do not recognise or a bad `range`
`key_limit_reached`	403	no	The web key used its AI units for the day or month
`key_not_found`	401	no	The web key does not exist or was revoked
`method_not_allowed`	405	no	The route exists but not for that method; see `Allow`
`model_not_found`	404	no	There is no model with that name
`model_unavailable`	503	yes	The model, and every one of its `fallbacks`, cannot answer right now, or it stopped partway through a stream
`not_found`	404	no	The route does not exist
`origin_not_allowed`	403	no	The web key does not work from the page’s address
`payload_too_large`	413	no	The body is over 8 MB for a chat call, or 1 MB for a management call
`prompt_exists`	409	no	The project already has a prompt with that name; save a new version of it instead
`prompt_in_use`	409	no	A task uses the prompt; change or delete the task first
`prompt_limit_reached`	403	no	The project already holds 100 prompts; delete one first
`prompt_not_found`	404	no	The project has no prompt with that name, or no such version of it
`rate_limited`	429	yes	The project sent more requests or tokens this minute than its plan allows; see `Retry-After`
`session_expired`	401	yes	A web page’s visit expired; start a new one
`task_disabled`	403	no	The task is turned off; turn it on in the console
`task_exists`	409	no	The project already has a task with that name
`task_limit_reached`	403	no	The project already holds 100 tasks; delete one first
`task_not_allowed`	403	no	The web key may not run that task
`task_not_found`	404	no	The project has no task with that name
`tokens_over_limit`	403	no	One call asks for more tokens than the plan allows in a whole minute
`too_many_sessions`	429	yes	Too many new visits came from one network this hour; see `Retry-After`
`unauthenticated`	401	no	The bearer token is missing or not one we accept
`unavailable`	503	yes	Something the request depends on is not available right now
`unit_limit_reached`	403	no	The call could go over the AI units the project may use this month
`unsupported_media_type`	415	no	The body is not `application/json`
`validation_failed`	422	no	Fields are wrong; the message or `issues` says which
`visitor_limit_reached`	429	yes	One visitor used their requests a minute or AI units a day; see `Retry-After`
`web_key_limit_reached`	403	no	The project already holds 20 web keys; revoke one first
`web_key_not_found`	404	no	The project has no web key with that ID

Last updated 1 October 2026