Errors
All errors use the standard envelope with success: false and a human‑readable
message. Validation errors add a data.errors map.
{ "success": false, "message": "Reason.", "data": { "errors": { "field": ["..."] } } }
Status codes
| Status | When | Example message |
|---|---|---|
200 |
Success | — |
401 |
Missing key | API key is required in the X-API-KEY header. |
401 |
Invalid/deactivated key | The provided API key is invalid or has been deactivated. |
402 |
Wallet balance too low for a lookup (not charged) | Insufficient wallet balance for this lookup. |
403 |
Key not linked to a partner | This API key is not linked to a Rupa partner account. |
403 |
Partner account not active | Your partner account is pending. Contact Riwe to activate API access. |
403 |
Caller IP not allow‑listed | This partner account is not permitted from your IP address. |
403 |
None of the requested sections permitted | None of the requested sections are permitted for your account type. |
404 |
Rupa ID has no farmer | No farmer found for that Rupa ID. |
404 |
Consent record not found (on revoke) | No consent record found for that Rupa ID. |
422 |
Request validation failed | Validation Error |
Examples
401 — bad or missing key
curl -X POST https://api.riwe.io/v1/rupa/lookup \
-H "X-API-KEY: wrong" -H "Content-Type: application/json" -d '{"rupa_id":"rp-7lif9u"}'
{ "success": false, "message": "The provided API key is invalid or has been deactivated." }
404 — unknown Rupa ID
{ "success": false, "message": "No farmer found for that Rupa ID." }
422 — missing required field
{
"success": false,
"message": "Validation Error",
"data": { "errors": { "rupa_id": ["The rupa id field is required."] } }
}
Handling guidance
401/403→ configuration issue (wrong key, inactive account, IP). Do not retry blindly; fix the setup.402→ top up the wallet, or request fewersections, then retry.404→ the farmer isn't on Riwe under that Rupa ID; confirm the ID with the farmer.422→ fix the request body per theerrorsmap.5xx(unexpected) → safe to retry with backoff; billed lookups auto‑refund on internal failure.