API errors
Handle errors programmatically by error_code and use detail only as a fallback.
application/problem+json
{
"type": "https://gota.umbeluzi.com/docs/api/errors#validation.field_required",
"title": "Unprocessable Entity",
"status": 422,
"detail": "A required field was missing or empty.",
"code": "VALIDATION_ERROR",
"error_code": "validation.field_required",
"params": {
"field": "name"
},
"request_id": "req_01J...",
"invalid_params": [
{
"name": "name",
"reason": "is required"
}
]
}Broad codes (code)
| Code | HTTP status | Meaning | Retryable |
|---|---|---|---|
INVALID_REQUEST | 400 | The request was malformed or failed validation. | No |
UNAUTHORIZED | 401 | Authentication is missing, invalid, or expired. | No |
FORBIDDEN | 403 | The authenticated caller lacks permission for this action. | No |
CAPABILITY_INACTIVE | 403 | The tenant capability required for this operation is not active. | No |
NOT_FOUND | 404 | The requested resource does not exist or is not visible in this context. | No |
CONFLICT | 409 | The request conflicts with the current resource state or an idempotency key. | No |
UNSUPPORTED_OPERATION | 400 | The requested operation is not supported for this resource. | No |
INTEGRATION_UNAVAILABLE | 503 | A downstream connector or integration is temporarily unavailable. | Yes |
EXTERNAL_RESOURCE_CONFLICT | 409 | An external integration reported a state conflict. | No |
RATE_LIMITED | 429 | The caller exceeded its request budget; retry after RateLimit-Reset. | Yes |
DEADLINE_EXCEEDED | 504 | The operation timed out before completion. | Yes |
INTERNAL_ERROR | 500 | An unexpected server error occurred. | Yes |
Specific codes (error_code)
| Code | Parameters | Meaning |
|---|---|---|
account.contact_in_use | None | An account already uses this email or phone. |
account.creation_review_required | None | This account needs a manual review before it can be created. Contact support to continue. |
account.limit_reached | None | This person has reached the allowed number of accounts. |
account_link.details_required | None | Enter the link code, or the utility, the contract or meter number, and the mobile phone. |
account_link.permission_not_delegable | None | This permission cannot be delegated. |
approval.self_approval | None | You cannot approve a request you made. |
auth.challenge_failed | None | We could not confirm you are not a robot. Try again. |
auth.challenge_required | None | Confirm you are not a robot and try again. |
auth.forbidden | None | You do not have permission for this action. |
auth.invalid_credentials | None | The sign-in details are incorrect. |
auth.ip_not_allowed | None | Your utility does not allow access from this network. |
auth.mfa_challenge_invalid | None | The verification request expired. Sign in again. |
auth.mfa_enrollment_required | None | Your utility requires two-factor verification. Enable it in Security to continue. |
auth.mfa_locked | None | Too many incorrect codes. Wait a few minutes and try again. |
auth.session_ended | None | This session was ended. Sign in again to continue. |
auth.sso_required | None | This utility requires sign-in through its identity provider (SSO). |
auth.step_up_required | None | Confirm your identity to continue. |
auth.token_expired | None | The code or link has expired. Request a new one. |
auth.unauthenticated | None | Your session has ended. Sign in again. |
capability.inactive | None | This capability is not active for the utility yet. |
cashier.shift_not_open | None | Open a cash desk shift first. |
connection.property_not_owned | None | This property does not belong to this customer. |
connector.lease_expired | None | This job's lease has expired. Try again. |
feature.not_configured | None | This feature is not set up yet. |
file.too_large | None | The file exceeds the size limit. |
file.type_unsupported | None | This file type is not accepted. |
identity.password_too_common | None | This password is too common. Choose another one. |
import.column_missing | column | The file is missing the {column} column. |
import.file_empty | None | The file has no rows to import. |
import.file_invalid | None | The file could not be read. Check its format. |
import.line_invalid | line | Line {line} of the file is incomplete or not valid. |
import.too_many_rows | max | The file has too many rows: at most {max} at a time. |
integration.bad_gateway | None | The external service could not be reached. |
integration.conflict | None | The external service refused the operation because of a conflict. |
integration.unavailable | None | The external service is not available. Try again later. |
inventory.insufficient_stock | None | There is not enough stock in the store. |
inventory.item_unavailable | None | Item {item} is not in the catalogue or is inactive. |
inventory.whole_units_only | None | {item} is counted in whole units. |
invoice.has_payments | None | This invoice has payments and cannot be voided. Issue a credit note instead. |
invoice.no_balance | None | This invoice has no balance due. |
invoice.not_open | None | This invoice is not open. |
invoice.void | None | This invoice is void. |
leak_allowance.ineligible | None | This invoice does not meet the leak allowance policy. |
meter.no_collector | None | This meter has no collector to carry commands. |
meter.no_reading_baseline | None | No accepted readings bound the consumption period. |
meter.serial_mismatch | None | The serial number does not match the meter. |
organization.owner_consent_required | None | The owner's consent is required. |
payment.method_not_configured | None | This payment method is not configured for this utility. |
payment.reference_in_use | None | This reference was already used. |
payment.session_mismatch | None | The payment does not match the payment session. |
proof.already_reviewed | None | This proof was already reviewed. |
reading.unit_mismatch | None | The reading unit does not match the meter unit. |
request.cursor_invalid | None | The requested page is no longer valid. Reload the list. |
request.idempotency_conflict | None | This request was already sent with different details. Reload and try again. |
request.invalid | None | The entered details are not valid. Review them and try again. |
request.payload_too_large | None | The file is too large. |
request.rate_limited | None | Too many attempts. Wait a moment and try again. |
request.timeout | None | The request took too long. Try again. |
request.unsupported | None | This operation is not supported. |
resource.already_exists | None | This record already exists. |
resource.conflict | None | This operation is not possible in the current state of the record. |
resource.gone | None | This address no longer exists. |
resource.not_found | None | Record not found. |
server.internal | None | A server error occurred. Try again in a moment. |
state.invalid_transition | None | This action is not possible in the current state of the record. |
subscription.connection_limit_reached | None | Your plan allows up to {max} active connections. Change plan to activate more. |
subscription.suspended | None | This utility subscription is suspended for non-payment. Settle the open invoice to resume making changes. |
validation.duplicate | field | Some values are repeated. Each entry must be unique. |
validation.end_before_start | None | The end date must be after the start date. |
validation.field_required | field | Fill in the required fields. |
validation.invalid_choice | field | Choose one of the available options. |
validation.invalid_format | field | One of the values is not in the right format. Review it and try again. |
validation.length_out_of_range | field, min, max | The text must be between {min} and {max} characters long. |
validation.must_be_future | field | The date must be in the future. |
validation.must_be_positive | field | Enter a value greater than zero. |
validation.must_not_be_future | field | The date cannot be in the future. |
validation.must_not_be_negative | field | The value cannot be negative. |
validation.out_of_range | field, min, max | The value must be between {min} and {max}. |
validation.reason_required | field | Enter a reason. |
validation.too_large | field, max | The value cannot be more than {max}. |
validation.too_long | field, max | The text is too long: use at most {max} characters. |
validation.too_many | field, max | Too many entries: at most {max}. |
validation.too_short | field, min | The text is too short: use at least {min} characters. |
validation.too_small | field, min | The value cannot be less than {min}. |
workspace.unavailable | None | This utility is suspended or closed. |