Errors

Errors

All error responses follow a consistent format:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable explanation.",
    "details": {}
  }
}

Error codes

Authentication errors

invalid_api_key — HTTP 401

No valid API key was found. Ensure your key is included in the X-API-Key header and hasn’t been rotated or revoked.

{
  "error": {
    "code": "invalid_api_key",
    "message": "No valid API key found. Include your key in the X-API-Key header."
  }
}

key_inactive — HTTP 403

The API key exists but has been deactivated.

Rate limiting

rate_limit_exceeded — HTTP 429

You’ve hit your daily request limit. The response includes a Retry-After header with seconds until midnight UTC.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You've reached your daily request limit for the spore tier. Resets at midnight UTC."
  }
}

Validation errors

outside_coverage — HTTP 422

The requested coordinates fall outside all coverage regions.

{
  "error": {
    "code": "outside_coverage",
    "message": "This location (33.70, -84.30) is beyond Canopi's current root network. We currently cover Oregon and Washington.",
    "details": {
      "suggestion": "Use GET /v1/coverage to see available regions."
    }
  }
}

no_nearby_data — HTTP 422

The coordinates are within coverage but no prediction data exists within the search radius. This can happen in non-forested areas (urban, agricultural, water) within Oregon/Washington.

invalid_species — HTTP 422

The species code wasn’t recognized.

{
  "error": {
    "code": "invalid_species",
    "message": "Species code 'QUAG' isn't in our seed bank. Did you mean 'QUGA' (Oregon White Oak)?",
    "details": {
      "suggestion": "Use GET /v1/species to see available species."
    }
  }
}

invalid_method — HTTP 422

The planting method isn’t available for predictions.

batch_too_large — HTTP 422

The batch request exceeds your tier’s limit.

{
  "error": {
    "code": "batch_too_large",
    "message": "Batch contains 25 requests, but your spore tier allows up to 10.",
    "details": {
      "submitted": 25,
      "tier_limit": 10,
      "tier": "spore"
    }
  }
}

Server errors

internal_error — HTTP 500

Something unexpected went wrong. These are rare and automatically flagged for investigation.