Errors

Forge uses conventional HTTP status codes and a consistent error envelope. Any non-2xx response has this shape:

{
  "status": "error",
  "error": {
    "code": "string",
    "message": "human-readable description",
    "doc_url": "https://forge-api.dev/docs/..."
  }
}

Always branch on error.code in your application logic, not on error.message, which is meant for humans and may be reworded over time.

Error codes

HTTP status	Code	Description
400	`invalid_params`	A parameter was missing or malformed — for example an out-of-range `lat`/`lon`, an unrecognized `units` value, or `days` outside 1–7.
401	`missing_api_key`	No `Authorization` header was provided.
401	`invalid_api_key`	The key was provided but is malformed, unknown, or revoked.
404	`not_found`	The requested resource doesn't exist — typically an unrecognized city name passed to `city`.
429	`rate_limited`	You've exceeded your plan's per-minute rate limit. See rate limits.
500	`internal_error`	An unexpected error occurred on Forge's side. Safe to retry with backoff.

Example bodies

Invalid parameter, such as a latitude outside -90..90:

{
  "status": "error",
  "error": {
    "code": "invalid_params",
    "message": "lat must be between -90 and 90",
    "doc_url": "https://forge-api.dev/docs/api/weather"
  }
}

Unknown city name:

{
  "status": "error",
  "error": {
    "code": "not_found",
    "message": "No location found matching 'atlantsi'",
    "doc_url": "https://forge-api.dev/docs/api/weather"
  }
}

Missing key:

{
  "status": "error",
  "error": {
    "code": "missing_api_key",
    "message": "No API key provided. Pass your key in the Authorization header: Bearer fg_live_...",
    "doc_url": "https://forge-api.dev/docs/authentication"
  }
}

Handling errors defensively

Treat 500 and 429 as retryable with backoff; treat 400, 401, and 404 as non-retryable — retrying the exact same request will fail the same way.
Surface not_found to end users as "we couldn't find that place," and consider falling back to the geocoding endpoint to offer suggestions.
Log meta.request_id from successful responses (or check response headers on errors) if you ever need to reference a specific call in a support request.
Validate lat/lon/units/days client-side before sending a request to avoid burning a rate-limit slot on a guaranteed 400.

Next steps

See rate limits for details on the 429 response, or the weather and geocode references for endpoint-specific parameter constraints.