Skip to Content
Prets Developer Portal

Errors

The error object every endpoint returns, what each HTTP status means, and which failed requests are safe to retry.

The Prets API uses HTTP status codes to say whether a request worked. A 2xx status means it succeeded. A 4xx status means Prets refused the request as sent: fix the request before you send it again. A 5xx status means something went wrong on the Prets side, or in a service Prets depends on.

Every 4xx and 5xx response has the same JSON body, so you can handle errors in one place.

The error object

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Invalid email address",
    "param": "contact.email",
    "requestId": "1-6728f3a1-4b8c2d9e0f1a2b3c4d5e6f70"
  }
}
FieldAlways presentDescription
typeYesThe error family: one of invalid_request_error, authentication_error, rate_limit_error, api_error. It follows from the HTTP status.
codeYesA stable, machine-readable reason, such as parameter_missing or case_closed. Branch on code, not on message.
messageYesA human-readable explanation for developers. The wording can change, so don't parse it, and don't show it to consumers as is.
paramNoThe request field the error is about, as a dotted path with array indexes, for example address.postalCode or lineItems[0].quantity. Only present when one field caused the error.
requestIdYesThe identifier of this request. The same value is sent in the X-Request-Id response header. Include it when you contact Prets support.

Each response reports one error. When a request has several invalid fields, Prets reports the first one it finds. Fix it and send the request again to see the next one.

The reference page of each endpoint lists the error statuses it can return, with an example body for each.

Error types

typeHTTP statusMeaning
invalid_request_error400, 403, 404, 409, 415, 422Prets refused the request as sent.
authentication_error401The API key is missing, invalid, or revoked.
rate_limit_error429Too many requests in a short time.
api_error500, 502, 503A failure on the Prets side, or in a service Prets depends on.

HTTP status codes

StatusMeaningWhat to do
400 Bad RequestA query, path, or header parameter is invalid, for example a malformed cursor or an unknown expand value. Also returned when the request body isn't valid JSON.Fix the request. param names the parameter when one caused it.
401 UnauthorizedThe API key is missing, invalid, or revoked.Check the Authorization: Bearer header and the key.
403 ForbiddenThe key is valid but isn't allowed to do this, for example managing event destinations without the org:events:manage permission.Use a key with the right permission.
404 Not FoundThe resource doesn't exist, or it belongs to another organization. Prets doesn't reveal whether resources of other organizations exist.Check the ID, and that you use the key of the organization that owns the resource.
409 ConflictThe request conflicts with the current state of a resource, for example posting a message to a closed case. Also returned while an identical request is still being processed.Read code. Only idempotency_in_progress is worth retrying unchanged.
415 Unsupported Media TypeThe request body isn't sent as JSON.Send the body with Content-Type: application/json.
422 Unprocessable ContentThe body is valid JSON but a field fails validation, or Prets can't act on a valid request, for example when no financing terms exist for an amount.Fix the field param names, or change the request.
429 Too Many RequestsYou sent too many requests in a short time.Retry with exponential backoff.
500 Internal Server ErrorSomething unexpected went wrong at Prets. The message is always Internal Server Error.Retry as described in Retrying requests. If it persists, contact support with the requestId.
502 Bad GatewayA service Prets depends on returned an invalid response.Retry with exponential backoff.
503 Service UnavailableA service Prets depends on didn't respond in time.Retry with exponential backoff.

Error codes

code gives the precise reason. Prets adds codes over time without a new API version, so handle a code you don't know by its HTTP status and type.

General codes

codeStatusMeaning
bad_request400The request is malformed, for example the body isn't valid JSON or the cursor is invalid.
parameter_missing400, 422A required field or parameter is missing.
parameter_invalid400, 422A field or parameter has an invalid value.
parameter_unknown400, 422The request contains a field the endpoint doesn't accept.
unauthorized401The API key is missing, invalid, or revoked.
forbidden403The key isn't allowed to perform this request.
not_found404The resource doesn't exist, or isn't visible to your organization.
conflict409The request conflicts with the current state of the resource. message says how.
unsupported_media_type415The body isn't sent as application/json.
rate_limited429Too many requests.
internal_error500An unexpected error at Prets.
bad_gateway502A service Prets depends on returned an invalid response.
service_unavailable503A service Prets depends on is unavailable or didn't respond in time.

Endpoint-specific codes

codeStatusReturned byMeaning
idempotency_in_progress409Creating a quote, a case, or an event destinationAn identical request is still being processed. Retry shortly; see Retrying requests.
case_already_open409Creating a case for a quoteThe quote already has an open case. The Location response header points to it (/v1/cases/{caseId}).
case_closed409Posting a case messageThe case is closed, so it no longer accepts messages.
event_destination_already_exists409Creating an event destinationYour organization already has an event destination. Update or delete it instead.

Retrying requests

Retry a request only when sending it again can't do any harm. A network timeout, or a connection that drops before you get a response, counts as a 500: you don't know whether Prets processed the request.

Safe to retry unchanged

  • Any GET request.
  • 409 with code idempotency_in_progress. Wait a moment, then send the same request again, with the same Idempotency-Key if you set one.
  • 429, 502, and 503.

Retry with care: 500 and timeouts on requests that change data

  • Create a quote: send the retry with the same Idempotency-Key header. A retry after the first attempt finished returns the original quote instead of creating a second one; a retry after it failed runs the request again. See Idempotent requests.
  • Post a merchant message on a case: set messageId on the first attempt and send the same messageId and body on the retry. Prets returns the stored message instead of posting it twice. The same messageId with a different body returns 409 conflict.
  • Create a case for a quote: a retry after the first attempt succeeded returns 409 case_already_open. Follow the Location header to the case.
  • Create an event destination: a retry after the first attempt succeeded returns 409 event_destination_already_exists. List your event destinations to find it.
  • Any other request: read the resource first, and only retry when the change isn't there yet.

Don't retry unchanged

400, 401, 403, 404, 415, 422, and any 409 other than idempotency_in_progress. The same request gets the same answer: fix it first.

Back off between attempts. Wait about one second before the first retry, double the wait after each attempt, add some random jitter, and stop after about five attempts.

A few errors happen in the infrastructure in front of the API, for example when traffic is throttled or a request takes too long. Their body is {"message": "..."}, without the error object. Handle them by their HTTP status: retry a 429 or 5xx like any other.

On this page