Errors and retries

AskElephant’s public API uses application/problem+json for error responses.

Error shape

{
  "type": "https://app.askelephant.ai/errors/validation_failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The request contains invalid fields.",
  "request_id": "rid_01ABC...",
  "errors": [
    {
      "field": "limit",
      "code": "invalid_range",
      "message": "limit must be between 1 and 100."
    }
  ]
}

Core fields

Common statuses in the live API

Rate limiting

Authenticated /api/v2 resource requests are limited to 1000 per workspace per 60-second window. The limit is shared across all credentials for the workspace and applies to every HTTP method on v2 resource routes.

Monitor rate-limit usage on successful responses via X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. When the limit is exceeded, the API returns 429 and includes Retry-After with the seconds to wait before retrying.

When rate-limit enforcement is temporarily unavailable, authenticated requests return 503 with problem type https://app.askelephant.ai/errors/rate_limit_unavailable. Retry after a short backoff; successful responses are not returned in that state.

See Rate limits for the full header reference and integrator guidance.

Retry guidance

• Retry 429 only after respecting Retry-After.
• Retry 503 rate_limit_unavailable with exponential backoff; do not assume the request succeeded.
• Do not retry 401 until you refresh or replace the credential.
• Do not retry 403 until the credential has the required scope.
• Do not retry 404 unless the resource may legitimately appear later.

Support tip

Include request_id when reporting issues to AskElephant so requests can be traced quickly.