Errors
The error format, how to handle each kind of error, and every error code.
Format
Every error answers with an HTTP status from 400 up and a problem object
(application/problem+json):
{
"status": 400,
"code": "invalid_request",
"detail": "The date window can be at most 31 days. Split the request into smaller windows.",
"requestId": "<request id>",
"errors": [{ "parameter": "endDate", "code": "out_of_range", "detail": "<how to fix it>" }],
"data": null
}| Field | Meaning |
|---|---|
status | The HTTP status, also in the body, so the object stands on its own (for example in logs). |
code | What went wrong. Switch on this field. |
detail | An English sentence on how to fix it. It may change: never parse it. |
requestId | The request's id, also sent as the Request-Id header. Give it to Pult support. |
errors | For invalid_request, every invalid parameter, each with its own code and detail; an empty list for every other code. |
data | Extra facts for some codes (for example data.scope), otherwise null. |
The codes in errors are required, invalid_format, invalid_value, out_of_range,
too_many_values and unknown_parameter.
The MCP server sends the same object. MCP Server says how it reaches the assistant.
Handle errors
- 400, 404, 413: fix the request; sending it again gives the same answer.
- 401, 403: fix the key, the connection or the organization's access (see Authentication). Retrying doesn't help.
- 429: wait the seconds in the
Retry-Afterheader or indata.retryAfterSeconds(the same value), then retry (see Rate limits). - 500: retry once. If it fails again, contact Pult support with the
requestId. - An unknown
code: new codes can appear at any time. Handle them by their status.
A request either succeeds as a whole or fails as a whole. You never get part of an answer.
Error catalogue
| Status | code | What it means | What to do |
|---|---|---|---|
| 400 | invalid_request | The request is invalid. errors lists each invalid parameter. | Fix the parameters as each detail says. |
| 400 | invalid_cursor | The cursor is invalid or was issued for other filters. | Repeat the request without a cursor to start on the first page. |
| 401 | invalid_api_key | No credential was sent, or the API key (a value starting with pult_) is malformed or unknown. | Send a valid key as Authorization: Bearer pult_<key>. |
| 401 | api_key_expired | The API key has expired. | Ask an admin of your organization for a new key. |
| 401 | api_key_revoked | The API key was revoked. | Ask an admin of your organization for a new key. |
| 401 | invalid_token | The bearer value is not a valid OAuth access token: it is unknown, expired, revoked or for another API, or its owner was archived or deleted. | Refresh the token. If that fails, connect the app to Pult again. For an API key, check that it starts with pult_. |
| 403 | organization_disabled | The organization is disabled or suspended, so its API access is paused. | Ask an admin of the organization to contact Pult support. |
| 403 | api_not_enabled | The API is not enabled for this organization. | Ask Pult support to enable it. |
| 403 | api_key_paused | The API key is paused. | An admin can see why in the Pult Dashboard. |
| 403 | connection_paused | The OAuth connection is paused because its owner is not an admin now. | Ask an admin of your organization. |
| 403 | insufficient_scope | The key or connection lacks the scope this endpoint needs (data.scope). | Use a key that holds it (a new key gets every current scope), or connect the app again with that scope. |
| 403 | feature_not_enabled | The organization has none of the products this endpoint needs (data.feature names one). | Ask Pult support to enable it. |
| 404 | not_found | No resource with this id exists in your organization (data.resource). | Check the id. |
| 404 | route_not_found | No endpoint exists at this path with this method. | Check the path and the API version. |
| 413 | payload_too_large | The request body is too large. | Send a smaller body. |
| 429 | rate_limited | Too many requests (the wait in Retry-After or data.retryAfterSeconds, the same value). | Wait that many seconds, then retry. |
| 500 | internal_error | An unexpected error occurred. | Retry once. If it persists, contact Pult support with the requestId. |
Last updated on