Errors
The error envelope, the error codes the API returns, and how to recover from each.
The API signals failures with standard HTTP status codes and a consistent JSON body. Anything with a status code of 300 or higher should be treated as a failure.
Error envelope
Every error response shares the same shape:
{
"status": 400,
"detail": "Human readable error message.",
"code": "validation_error"
}| Field | Type | Description |
|---|---|---|
status | integer | Mirrors the HTTP status code. Anything greater than 299 is a failure. |
detail | string | Human-readable message. Useful for logs, but do not branch on its exact text. |
code | string | Stable, machine-readable code. Branch on this. For 5xx errors it is a tracking UUID; include it when contacting support. |
Branch your error handling on code, not on detail, since the human-readable message may change.
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:
code | Meaning | How to recover |
|---|---|---|
missing_fields | A required field was absent. | Add the missing field(s) named in detail. |
validation_error | The request failed validation. | Fix the fields named in detail. |
invalid_body | The request body could not be parsed. | Send valid JSON with Content-Type: application/json. |
invalid_field | A field had an unexpected name or type. | Correct the field to match the endpoint's schema. |
unsupported_value | A field held a value the API doesn't accept. | Use a supported value (check the endpoint reference). |
empty_value | A field was present but empty. | Provide a non-empty value. |
invalid_parameter | A query or path parameter was invalid. | Correct the parameter named in detail. |
invalid_credentials | Authentication failed. | Check your x-api-key and x-client-id. See Authentication. |
invalid_batch_size | The batch size was outside the allowed range. | Reduce the number of items in the batch. |
max_batch_size_exceeded | The batch exceeded the maximum item count. | Split the request into smaller batches. |
http_validation_error | The request failed structural validation. | Review the request against the endpoint schema. |
unsupported_profession | The professionCode isn't recognized. | Use a code returned by GET /v2/professions. |
unsupported_state | The professionState isn't supported for this profession. | Confirm the state/profession pairing via GET /v2/professions. |
restricted_profession | Your account isn't authorized for this profession. | Contact support@propelus.com to request access. |
restricted_state | Your account isn't authorized for this state. | Contact support@propelus.com to request access. |
restricted_environment | The operation isn't allowed in this environment. | Confirm you're calling the correct environment. |
Rate limiting (429)
A 429 Too Many Requests means you've exceeded your rate limit. The response includes a Retry-After header (seconds to wait) and the standard envelope. Honor Retry-After before retrying. 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).
- The
codefield is a tracking UUID. Include it, along with the approximate timestamp, when you contact support@propelus.com so the issue can be traced.