Error Codes

All errors follow the RFC 7807 Problem Details format.

Error Response Format


{
  "type": "https://api.gotamil.in/problems/{error-code}",
  "title": "Human-readable title",
  "status": 400,
  "detail": "Detailed explanation",
  "request_id": "fastify-request-id",
  "errors": [{ "field": "text", "message": "Required" }]
}

The errors array is present only for validation errors.

Error Code Reference

Code	Status	Description
`unauthorized`	401	Missing or invalid Bearer token
`forbidden`	403	Insufficient role or permissions
`not-found`	404	Resource not found
`validation-error`	400	Request schema validation failed
`idempotency-in-progress`	409	Duplicate idempotency key being processed
`operation-claim-failed`	503	Failed to claim operation for processing
`async-enqueue-failed`	503	Failed to enqueue async task
`provider-error`	502	Provider API request failed
`provider-unavailable`	503	All configured models failed
`provider-request-rejected`	502	Provider rejected request (non-retryable)
`provider-config-missing`	500	Tenant provider config not found
`server-misconfiguration`	500	Missing required configuration
`internal-error`	500	Unexpected server error

Common Scenarios

401 Unauthorized

Your bearer token is missing, expired, or malformed. Ensure your OIDC token is fresh and includes the required tenant_id claim.

403 Forbidden

Your token is valid but lacks the required role. Check the authorization matrix.

409 Idempotency In Progress

You sent a request with the same Idempotency-Key that is currently being processed by another request. Wait and retry, or use a new idempotency key.

502 Provider Error

The upstream Gemini API returned an error. The API retries automatically with model fallback chains. If you see this consistently, validate your BYOK credentials.

503 Provider Unavailable

All models in the fallback chain have been exhausted. This typically indicates a widespread provider outage or invalid credentials.