Changelog

Errors

Error code updates

API key errors now return `401` with the standard error envelope

If a request has a missing, invalid, or disabled API key, the API now returns 401 with the same error envelope as every other error:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is missing, disabled, or invalid. Pass a valid key in the x-api-key header."
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Previously these requests returned 403 with a bare {"message": "Forbidden"} body.

Unknown routes now return `404`

A request to a path that doesn’t exist now returns 404 with the code not_found. The details object shows the method and path you called:

{
  "error": {
    "code": "not_found",
    "details": { "method": "GET", "path": "/v1/widgets/123" },
    "message": "No such route."
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Previously, some unknown paths returned 403 with {"message": "Missing Authentication Token"}, even with a valid key.

Per-second rate limits now return `rate_limited`

Calls over the per-second rate limit still return 429, now with the standard error envelope and the code rate_limited:

{
  "message": "Too Many Requests", 
  "error": {
    "code": "rate_limited",
    "message": "Too many requests per second."
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Previously these returned a bare {"message": "Too Many Requests"} body. Use error.code to tell them apart from quota_exceeded, which means your quota for the period is used up. Rate-limited responses don’t include Retry-After or X-RateLimit-* headers; back off briefly and retry.

Timeouts now return `timeout_error`

Requests that time out still return 504, now with the standard error envelope and the code timeout_error:

{
  "message": "Endpoint request timed out",
  "error": {
    "code": "timeout_error",
    "message": "The request timed out. Please wait a few minutes and try again."
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Previously these returned a bare {"message": "Endpoint request timed out"} body. Timeout responses include Retry-After: 120; wait that many seconds before retrying the same request.

Server failures now return `internal_error`

When the API fails before it can respond, it still returns 502, now with the standard error envelope and the code internal_error:

{
  "message": "Internal server error",
  "error": {
    "code": "internal_error",
    "message": "Something went wrong."
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Previously these returned a bare {"message": "Internal server error"} body.

Every other error now uses the standard error envelope

All errors now return the standard envelope.

Other 4xx errors, such as a request that’s too large, return the code bad_request. error.details.type names the specific reason, for example REQUEST_TOO_LARGE.
Other 5xx errors return the code internal_error.

Include the request_id when you contact support about an error.

Get started

Cards

Certs

Specs

Catalogs

API key errors now return `401` with the standard error envelope

Unknown routes now return `404`

Per-second rate limits now return `rate_limited`

Timeouts now return `timeout_error`

Server failures now return `internal_error`

Every other error now uses the standard error envelope

​API key errors now return 401 with the standard error envelope

​Unknown routes now return 404

​Per-second rate limits now return rate_limited

​Timeouts now return timeout_error

​Server failures now return internal_error

​Every other error now uses the standard error envelope

API key errors now return `401` with the standard error envelope

Unknown routes now return `404`

Per-second rate limits now return `rate_limited`

Timeouts now return `timeout_error`

Server failures now return `internal_error`

Every other error now uses the standard error envelope