Errors

The API signals failures with standard HTTP status codes and, in most cases, a consistent JSON body. Anything with a status code of 300 or higher should be treated as a failure.

Error envelope

Every error response returned by the API shares the same shape. A few errors are returned before the request reaches the API and use a different body (see Errors outside the envelope):

{
  "status": 400,
  "detail": "Human readable error message.",
  "code": "validation_error"
}

Branch your error handling on code, not on detail, since the human-readable message may change. Only the error envelope has a code field.

Errors outside the envelope

These errors are returned before the request reaches the API. Their body is not the error envelope and has no code field:

Branch on the HTTP status first, and read code only when the body is the error envelope. Don't assume every error body is JSON, and don't branch on the message text, since it may change.

Request bodies between 6 MB and 10 MB do reach the API, and are rejected with 400 and code: validation_error.

Client errors (4xx)

Client errors mean the request needs to be changed before retrying; an identical retry will fail the same way. The code field takes one of these values:

Rate limiting (429)

A 429 Too Many Requests means you've exceeded your rate limit. Its body is { "message": "..." } rather than the standard envelope (see Errors outside the envelope). Retry with exponential backoff and jitter; see Rate limits for the full backoff strategy.

Server errors (5xx)

A 5xx indicates a problem on the Propelus side, not with your request. These are safe to retry:

• Retry with exponential backoff and jitter (see Rate limits).
• When the API returns the error, the code field is unexpected_error. A 504 returned before the request reaches the API has no code (see Errors outside the envelope); retry it the same way. If the error persists, contact support@propelus.com with the endpoint you called and the approximate timestamp so the issue can be traced.