Error Codes

Reference of all Forge error codes.

Error Codes

Forge uses standard HTTP status codes along with detailed error objects in the response body. All errors follow a consistent format.

Error Response Format

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 30 seconds.",
    "type": "rate_limit_error",
    "param": null,
    "retry_after": 30
  }
}

HTTP Status Codes

Code	Type	Description
`400`	invalid_request_error	The request was malformed or missing required parameters.
`401`	authentication_error	Invalid, expired, or missing API key.
`402`	payment_required	x402 payment required for this feature or module.
`403`	permission_error	API key lacks permission, or feature not available on current tier.
`404`	not_found	Requested resource does not exist.
`409`	conflict	Resource conflict (e.g., duplicate agent name).
`422`	validation_error	Request passed parsing but failed validation.
`429`	rate_limit_error	Too many requests. Check `retry_after` in response.
`451`	security_block	Request blocked by ForgeGuard security pipeline.
`500`	internal_error	Unexpected server error. Contact support if persistent.
`502`	provider_error	Upstream LLM provider returned an error.
`503`	service_unavailable	All providers unavailable or service is in maintenance.
`504`	timeout_error	Request timed out waiting for provider response.

Forge-Specific Error Codes

Code	Description
`forge_routing_failed`	No suitable model found for the request constraints.
`forge_security_blocked`	Request blocked by security pipeline (S1-S7).
`forge_memory_unavailable`	Memory service is temporarily unavailable.
`forge_tier_insufficient`	Feature requires a higher subscription tier.
`forge_budget_exceeded`	Cost budget exceeded for this request or period.
`forge_circuit_open`	Circuit breaker tripped due to excessive cost or errors.
`forge_connect_auth_failed`	Connected app authentication failed or expired.

Environment Variables

Rate Limits

Back to all documentation