Skip to main content

Errors - APIv2

Updated

The error envelope, 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. 

Any status result code of 300 or higher should be treated as a failure.

Source: https://propelus.com/developer/getting-started/errors

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 code field is a tracking UUID. Include it, along with the approximate timestamp, when you contact support@propelus.com so the issue can be traced.

Related articles