Skip to content
AgroSatAgroSat API

Errors

Every failed request returns the error envelope with a stable code and an English message:

{
  "success": false,
  "error": {
    "code": "field_not_found",
    "message": "Field not found."
  }
}

Branch on code and the HTTP status. Messages are for people and may change. Some errors carry an extra member inside error, such as existing_field_id.

Errors are never billed. Image requests return this JSON envelope with Content-Type: application/json instead of an image.

Error codes

Section titled “Error codes”
Status code Meaning What to do
202 data_pending The data is being prepared. Not an error; see Field readiness. Wait Retry-After seconds and repeat.
400 invalid_request A parameter or the body is malformed: a missing member, a bad date, limit or width out of range, an unknown format or source, an invalid cursor. Fix the request.
400 invalid_geometry The geometry is not a valid WGS84 Polygon or MultiPolygon, or it intersects itself. Fix the boundary.
400 field_too_large The field is larger than the per-field limit of your contract. Split the field or ask to raise the limit.
400 invalid_index Unknown index, or one the chosen source does not support. Use an index from the list.
400 invalid_date_range to is before from, or the window is longer than 366 days. Shorten the window.
400 date_out_of_range The window starts before the earliest date your contract allows. The message names that date. Start the window later.
401 invalid_api_key The key is missing, unknown, revoked or expired, or API access for your organization is off. Check the key; see Authentication.
403 quota_exceeded Monthly units or contracted hectares are used up. Wait for the next month or contact AgroSat.
403 source_not_enabled source=planet without a Planet agreement. Use sentinel-2, or contact AgroSat.
404 field_not_found No field with this id among your organization’s API fields. Also returned for deleted fields. Check the id.
404 no_imagery_for_date No imagery for that date, or it cannot be rendered. Pick a date from dates.
404 not_found No such endpoint, or the method is not supported on it. Check the method and path.
409 external_id_conflict The external_id is already used by a field with a different geometry. error.existing_field_id names it. Use another external_id, or delete the old field first.
409 duplicate_geometry The field overlaps one you registered by more than 80 % of its area. error.existing_field_id names it. Use the existing field.
429 rate_limited Too many requests with this key in the last minute, or several registrations for your organization at the same moment. Wait Retry-After seconds; see Rate limits.
500 internal_error An unexpected failure on our side. Retry with a growing delay. If it persists, contact AgroSat with the time, endpoint and field id.

Retrying

Section titled “Retrying”
Response Retry?
202, 429 Yes, after Retry-After seconds.
500 and network errors Yes, with exponential backoff. Registration is safe to repeat; see Registering fields.
Other 4xx No. The same request fails the same way until you change it or your contract changes.

Next steps

Section titled “Next steps”
API referenceWhich errors each endpoint can return.
Field readinessEverything about 202 data_pending.