Skip to main content
When a request fails, the Bhumi API returns a JSON error object alongside the appropriate HTTP status code. Error responses are structured consistently across all endpoints so you can handle them uniformly in your code.

​
Error response format

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "lat and lng are required.",
    "status": 400
  }
}
​
error.code
string
A machine-readable error code string. Use this in your application logic to classify errors programmatically.
​
error.message
string
A human-readable description of what went wrong. Safe to log and display in developer-facing output.
​
error.status
number
The HTTP status code, mirrored inside the response body for convenience.

​
HTTP status codes

StatusCode stringMeaning
200—Request succeeded. The response body contains the requested data.
400BAD_REQUESTOne or more query or path parameters are invalid or missing. Fix the request before retrying.
401UNAUTHORIZEDThe X-API-Key header is missing, malformed, or the key does not exist.
403FORBIDDENThe key is valid and active but does not have permission for this operation (e.g., accessing a paid-tier field with a free-tier key).
404NOT_FOUNDThe requested resource — typically a farm ID — does not exist in the dataset.
429RATE_LIMITEDYour key has exceeded the request limit for the current window. Check X-RateLimit-Remaining before sending further requests.
500INTERNAL_ERRORAn unexpected server-side error occurred. This is not caused by your request and is safe to retry.

​
Retry guidance

Do not retry 4xx errors without changing your code or request. These indicate a problem with the request itself, not a transient server condition.

​
When to retry

Retry on 429 and 500 responses using exponential backoff:
  1. Wait before the first retry (e.g., 1 second).
  2. Double the wait time on each subsequent attempt (e.g., 2 s, 4 s, 8 s).
  3. Add a small random jitter to avoid synchronized retry storms when multiple clients hit the limit simultaneously.
  4. Cap the maximum wait time (e.g., 60 seconds) and the number of attempts (e.g., 5).
For 429 specifically, inspect the X-RateLimit-Remaining header. If it reaches 0, pause all requests until the rate limit window resets rather than issuing retries immediately.

​
When not to retry

Do not retry these without fixing the underlying issue first:
  • 400 BAD_REQUEST — Your request is missing a required parameter or contains an invalid value. Correct the request.
  • 401 UNAUTHORIZED — Your API key is missing or invalid. Verify the key value and that the X-API-Key header is being set.
  • 403 FORBIDDEN — Your key does not have access to the requested resource or field. Check your plan tier.
  • 404 NOT_FOUND — The farm ID you requested does not exist. Verify the ID in your data.

​
Example error responses

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "lat and lng are required.",
    "status": 400
  }
}
All error responses still include the X-RateLimit-Limit and X-RateLimit-Remaining headers, so you can track your usage budget even when a request fails.