Browse API documentation
API documentation

Errors

Search API documentation
    v1

    The Fathom API uses conventional HTTP status codes to indicate the result of a request. Codes in the 2xx range mean success, codes in the 4xx range indicate a problem with the information you supplied (a missing parameter, an invalid token, a permissions issue, and so on), and codes in the 5xx range indicate an error on our side (these are rare).

    Always send Accept: application/json so that errors are returned as JSON rather than an HTML error page. Most errors return a single error key with a human-readable message. Validation errors (for example, a missing required field) instead return an errors object keyed by field name, with an array of messages for each field.

    Status Meaning When you'll see it
    400 Bad Request The request was rejected. This covers invalid or missing parameters, a failed validation check (returned as an errors object, for example an aggregation limit above 1000), a token that lacks permission for the action, an unsupported entity, an hourly date_grouping over a range longer than 7 days, or an account whose subscription has lapsed.
    401 Unauthorized Your API token is missing, malformed or no longer valid. Check the Authorization: Bearer header you're sending.
    404 Not Found The site, event or milestone you referenced doesn't exist, or your token doesn't have access to it.
    410 Gone The endpoint has been retired and no longer functions. This currently applies to the legacy Wipe Site and Wipe Event endpoints, and to renaming an event with the legacy Update Event endpoint.
    422 Unprocessable Entity The request was understood but can't be fulfilled, typically an aggregation that combines incompatible fields or groupings.
    429 Too Many Requests You've exceeded a rate limit or your concurrency limit. Check the Retry-After response header and back off before retrying.
    500 Server Error Something went wrong on our end. These are rare and we're alerted automatically. Retry shortly, and contact us if it persists.
    503 Service Unavailable Our analytics API is briefly at capacity. Check the Retry-After response header and retry shortly.

    Branch on the status code

    Error messages are written for humans and may change over time. When handling errors programmatically, branch on the HTTP status code rather than matching on the message text.
    General error400
    {
    "error": "This token doesn't have permission to access this endpoint"
}
    Validation error400
    {
    "errors": {
        "name": [
            "The name field is required."
        ]
    }
}
    Unauthorized401
    {
    "error": "Unauthenticated"
}
    Rate limited429
    {
    "message": "Too Many Attempts."
}
    Concurrency limit reached429
    {
    "error": {
        "code": "api_concurrency_limit_reached",
        "message": "You have too many API requests in flight at once. Your current API plan allows up to 5 concurrent requests. Wait for some to finish, or upgrade to Tier 3 for 10 concurrent requests at $39/mo. See https://usefathom.com/api/v1/rate-limits for details.",
        "limit": 5,
        "next_tier": {
            "name": "Tier 3",
            "concurrent_queries": 10,
            "price": "$39/mo"
        }
    }
}