Errors, rate limits, and retries - Hobbes Customer Hub

Hobbes returns JSON errors with a detail field and attaches X-Request-ID to successful and failed requests. Authentication, authorization, missing resource, rate-limit, and server errors use a string:

{
  "detail": "Insufficient scope"
}

Validation errors use an array so each invalid path or query parameter can be identified separately:

{
  "detail": [
    {
      "type": "less_than_equal",
      "loc": ["query", "limit"],
      "msg": "Input should be less than or equal to 200",
      "input": "201"
    }
  ]
}

Status codes

Status	Meaning	Retry?
`200`	Request succeeded	No
`202`	Asynchronous job accepted	Poll the job URL
`304`	Polled job is unchanged	Continue after the polling interval
`401`	Key missing or invalid	No, replace or fix the key
`403`	Required scope missing	No, create a correctly scoped key
`404`	Resource unavailable to this organization	No
`409`	Idempotency key conflict or delivery URL unavailable	No, correct the request
`422`	Path or query parameter failed validation	No, fix the request
`429`	Request, transcript, Custom Link, render, or organization queue quota exceeded	Yes, after `Retry-After`
`503`	Global queue or worker circuit breaker unavailable	Yes, after `Retry-After`
`5xx`	Temporary server failure	Yes, with exponential backoff

Rate limits

Keys allow 120 requests per 60-second window by default. Hobbes may configure a different limit for a specific key. Custom Link creation, thumbnail, and retry operations also allow 10 requests per minute per organization. Job polling allows 300 per minute per organization while retaining the lower 120-per-key limit. Creation and thumbnail compute have separate weighted hourly and daily quotas; see Create Custom Links.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117

On 429, sleep for the number of seconds in Retry-After. Add jitter if many workers share the same key.

import random
import time

if response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", "30"))
    time.sleep(retry_after + random.random())

For 5xx and network failures, retry a bounded number of times with exponential backoff. Do not retry authentication, authorization, validation, or missing resource errors.

Support diagnostics

Log these values for every failed request:

HTTP method and path, excluding secret query data
Response status and detail
X-Request-ID
Attempt number and next retry time

Never log the Authorization or x-api-key header.

​Status codes

​Rate limits

​Support diagnostics

Status codes

Rate limits

Support diagnostics