Error handling

Errors use HTTP status codes and a JSON body that usually includes a type (short code) and description (human-readable message). Your integration should log the full body when troubleshooting.

Common situations

HTTP status	Typical type (examples)	What it usually means for you
400	INVALID_REQUEST	Invalid JSON, missing fields, or values out of range (for example bad wb_window or coordinates).
401	NO_AUTH_KEY	No Authorization header or empty token.
403	INVALID_AUTH_KEY, ACCOUNT_EXPIRED	Token rejected or account access ended.
403	OUT_OF_BOUND_LOCATION	The point is outside the geographic area served for flood models in this deployment.
404	NO_SPATIAL_COORDINATES	Address endpoint only — the address could not be geocoded to coordinates.
429	TOO_MANY_REQUESTS	Slow down; you are sending requests too quickly.
429	QUOTA_REACHED	Contract quota exceeded; contact Geosapiens.
500	INTERNAL_SERVER_ERROR, NO_DATA	Server or data issue; retry later and contact support if it persists.

Exact type strings may match your environment’s release; always use statusCode and description for user messaging if you need a stable text.

Example error body

{
  "uuid": "739cf562-1016-4275-aafd-42f9e5102fa3",
  "timeStamp": "2023-8-11 14:51:55 UTC",
  "statusCode": 401,
  "status": "Unauthorized",
  "type": "NO_AUTH_KEY",
  "description": "An authorization token is required to access this resource."
}

Some errors also return a details object with per-field information. For the Essential API, those details refer to the seven score fields when applicable.