Errors

Rangler returns errors in one consistent format so integrations can handle failures reliably.

Rangler does not add generic status/message/data fields around successful responses.

successful reads return resource-shaped JSON
list endpoints return list-shaped JSON
errors always use the format below

Error format

{
  "error": {
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "28fa6152-7081-492e-8a7e-00beb237b689"
  }
}

Fields

Field	Type	Meaning
`error.type`	string	Broad error class
`error.code`	string	Stable application code for programmatic handling
`error.message`	string	Human-readable message
`error.request_id`	string	Request correlation ID for support and debugging
`error.details`	object or array or `null`	Optional structured context

Common status codes

Status	Meaning	Typical cause
`400`	Bad Request	malformed request shape or unsupported parameters
`401`	Unauthorized	missing, invalid, expired, revoked, or wrong-environment key
`403`	Forbidden	organization inactive or action not allowed
`404`	Not Found	company, filing, or other resource does not exist
`409`	Conflict	resource-state conflict, or an idempotency-key conflict on an endpoint that documents idempotent writes
`422`	Unprocessable Entity	validation failure
`429`	Too Many Requests	rate limit exceeded
`500`	Internal Server Error	unexpected Rangler error

Example: missing authentication

The financial endpoint returned this response when called without an API key:

{
  "error": {
    "type": "unauthorized",
    "code": "unauthorized",
    "message": "Authentication required.",
    "request_id": "28fa6152-7081-492e-8a7e-00beb237b689"
  }
}

Example: unknown financial selector

Rangler rejects unknown selector keys instead of silently returning a different dataset:

{
  "error": {
    "type": "unknown_ratio",
    "code": "unknown_ratio",
    "message": "Unknown ratio value(s): net_margin",
    "request_id": "7e4f2525-ca82-4f1a-a261-005c757c92cf",
    "details": {
      "allowed": [
        "gross_margin",
        "net_interest_margin",
        "pat_margin",
        "return_on_equity"
      ]
    }
  }
}

Example: rate limited

{
  "error": {
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "28fa6152-7081-492e-8a7e-00beb237b689"
  }
}

Headers worth handling

When Rangler rate limits a request, integrations should check:

Retry-After
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset