Getting Started/Errors & rate limits

Errors & rate limits

Error responses keep the same envelope shape — success: false, a machine-readable error code, a human-readable message, and an optional fix the agent can hand to a user.

Error envelope

{
  "success": false,
  "error": "validation_error",
  "message": "The property blog_name is required in the JSON body.",
  "fix": "Include blog_name in the JSON body, e.g. {\"blog_name\": \"My blog\"}."

When a scope is missing, the response also includes a required_scope field naming the permission needed:

{
  "success": false,
  "error": "insufficient_scope",
  "message": "This action requires a scope your key does not have.",
  "required_scope": "…"
}

Error codes

unauthorized

401Optional

The Authorization header is missing or the token format is invalid. Keys must start with fk_live_.

invalid_api_key

401Optional

The key was not found or has been revoked. Rotate it from the dashboard.

insufficient_scope

403Optional

The key is valid but doesn't have permission to perform this action. Regenerate your key with the correct scopes from the dashboard.

validation_error

400Optional

The request body is invalid JSON or a required parameter is missing or empty.

not_found

404Optional

No route matches the method and path you requested. Use GET /actions to list valid routes.

rate_limit_exceeded

429Optional

You've hit the per-key rate limit. The response includes a Retry-After: 60 header. Back off and retry after 60 seconds.

Rate limits

All API keys are limited to 60 requests per minute. When the limit is exceeded the API responds with 429 rate_limit_exceeded and sets:

Retry-After: 60 — seconds to wait before retrying.