Pult Docs

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
}
FieldMeaning
statusThe HTTP status, also in the body, so the object stands on its own (for example in logs).
codeWhat went wrong. Switch on this field.
detailAn English sentence on how to fix it. It may change: never parse it.
requestIdThe request's id, also sent as the Request-Id header. Give it to Pult support.
errorsFor invalid_request, every invalid parameter, each with its own code and detail; an empty list for every other code.
dataExtra 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-After header or in data.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

StatuscodeWhat it meansWhat to do
400invalid_requestThe request is invalid. errors lists each invalid parameter.Fix the parameters as each detail says.
400invalid_cursorThe cursor is invalid or was issued for other filters.Repeat the request without a cursor to start on the first page.
401invalid_api_keyNo 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>.
401api_key_expiredThe API key has expired.Ask an admin of your organization for a new key.
401api_key_revokedThe API key was revoked.Ask an admin of your organization for a new key.
401invalid_tokenThe 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_.
403organization_disabledThe organization is disabled or suspended, so its API access is paused.Ask an admin of the organization to contact Pult support.
403api_not_enabledThe API is not enabled for this organization.Ask Pult support to enable it.
403api_key_pausedThe API key is paused.An admin can see why in the Pult Dashboard.
403connection_pausedThe OAuth connection is paused because its owner is not an admin now.Ask an admin of your organization.
403insufficient_scopeThe 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.
403feature_not_enabledThe organization has none of the products this endpoint needs (data.feature names one).Ask Pult support to enable it.
404not_foundNo resource with this id exists in your organization (data.resource).Check the id.
404route_not_foundNo endpoint exists at this path with this method.Check the path and the API version.
413payload_too_largeThe request body is too large.Send a smaller body.
429rate_limitedToo many requests (the wait in Retry-After or data.retryAfterSeconds, the same value).Wait that many seconds, then retry.
500internal_errorAn unexpected error occurred.Retry once. If it persists, contact Pult support with the requestId.

Last updated on

On this page