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"
}
}| Field | Always present | Description |
|---|---|---|
type | Yes | The error family: one of invalid_request_error, authentication_error, rate_limit_error, api_error. It follows from the HTTP status. |
code | Yes | A stable, machine-readable reason, such as parameter_missing or case_closed. Branch on code, not on message. |
message | Yes | A human-readable explanation for developers. The wording can change, so don't parse it, and don't show it to consumers as is. |
param | No | The 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. |
requestId | Yes | The 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
type | HTTP status | Meaning |
|---|---|---|
invalid_request_error | 400, 403, 404, 409, 415, 422 | Prets refused the request as sent. |
authentication_error | 401 | The API key is missing, invalid, or revoked. |
rate_limit_error | 429 | Too many requests in a short time. |
api_error | 500, 502, 503 | A failure on the Prets side, or in a service Prets depends on. |
HTTP status codes
| Status | Meaning | What to do |
|---|---|---|
400 Bad Request | A 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 Unauthorized | The API key is missing, invalid, or revoked. | Check the Authorization: Bearer header and the key. |
403 Forbidden | The 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 Found | The 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 Conflict | The 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 Type | The request body isn't sent as JSON. | Send the body with Content-Type: application/json. |
422 Unprocessable Content | The 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 Requests | You sent too many requests in a short time. | Retry with exponential backoff. |
500 Internal Server Error | Something 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 Gateway | A service Prets depends on returned an invalid response. | Retry with exponential backoff. |
503 Service Unavailable | A 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
code | Status | Meaning |
|---|---|---|
bad_request | 400 | The request is malformed, for example the body isn't valid JSON or the cursor is invalid. |
parameter_missing | 400, 422 | A required field or parameter is missing. |
parameter_invalid | 400, 422 | A field or parameter has an invalid value. |
parameter_unknown | 400, 422 | The request contains a field the endpoint doesn't accept. |
unauthorized | 401 | The API key is missing, invalid, or revoked. |
forbidden | 403 | The key isn't allowed to perform this request. |
not_found | 404 | The resource doesn't exist, or isn't visible to your organization. |
conflict | 409 | The request conflicts with the current state of the resource. message says how. |
unsupported_media_type | 415 | The body isn't sent as application/json. |
rate_limited | 429 | Too many requests. |
internal_error | 500 | An unexpected error at Prets. |
bad_gateway | 502 | A service Prets depends on returned an invalid response. |
service_unavailable | 503 | A service Prets depends on is unavailable or didn't respond in time. |
Endpoint-specific codes
code | Status | Returned by | Meaning |
|---|---|---|---|
idempotency_in_progress | 409 | Creating a quote, a case, or an event destination | An identical request is still being processed. Retry shortly; see Retrying requests. |
case_already_open | 409 | Creating a case for a quote | The quote already has an open case. The Location response header points to it (/v1/cases/{caseId}). |
case_closed | 409 | Posting a case message | The case is closed, so it no longer accepts messages. |
event_destination_already_exists | 409 | Creating an event destination | Your 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
GETrequest. 409with codeidempotency_in_progress. Wait a moment, then send the same request again, with the sameIdempotency-Keyif you set one.429,502, and503.
Retry with care: 500 and timeouts on requests that change data
- Create a quote: send the retry with the same
Idempotency-Keyheader. 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
messageIdon the first attempt and send the samemessageIdandbodyon the retry. Prets returns the stored message instead of posting it twice. The samemessageIdwith a differentbodyreturns409 conflict. - Create a case for a quote: a retry after the first attempt succeeded returns
409 case_already_open. Follow theLocationheader 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.