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)

CodeHTTP statusMeaningRetryable
INVALID_REQUEST400The request was malformed or failed validation.No
UNAUTHORIZED401Authentication is missing, invalid, or expired.No
FORBIDDEN403The authenticated caller lacks permission for this action.No
CAPABILITY_INACTIVE403The tenant capability required for this operation is not active.No
NOT_FOUND404The requested resource does not exist or is not visible in this context.No
CONFLICT409The request conflicts with the current resource state or an idempotency key.No
UNSUPPORTED_OPERATION400The requested operation is not supported for this resource.No
INTEGRATION_UNAVAILABLE503A downstream connector or integration is temporarily unavailable.Yes
EXTERNAL_RESOURCE_CONFLICT409An external integration reported a state conflict.No
RATE_LIMITED429The caller exceeded its request budget; retry after RateLimit-Reset.Yes
DEADLINE_EXCEEDED504The operation timed out before completion.Yes
INTERNAL_ERROR500An unexpected server error occurred.Yes

Specific codes (error_code)

CodeParametersMeaning
account.contact_in_useNoneAn account already uses this email or phone.
account.creation_review_requiredNoneThis account needs a manual review before it can be created. Contact support to continue.
account.limit_reachedNoneThis person has reached the allowed number of accounts.
account_link.details_requiredNoneEnter the link code, or the utility, the contract or meter number, and the mobile phone.
account_link.permission_not_delegableNoneThis permission cannot be delegated.
approval.self_approvalNoneYou cannot approve a request you made.
auth.challenge_failedNoneWe could not confirm you are not a robot. Try again.
auth.challenge_requiredNoneConfirm you are not a robot and try again.
auth.forbiddenNoneYou do not have permission for this action.
auth.invalid_credentialsNoneThe sign-in details are incorrect.
auth.ip_not_allowedNoneYour utility does not allow access from this network.
auth.mfa_challenge_invalidNoneThe verification request expired. Sign in again.
auth.mfa_enrollment_requiredNoneYour utility requires two-factor verification. Enable it in Security to continue.
auth.mfa_lockedNoneToo many incorrect codes. Wait a few minutes and try again.
auth.session_endedNoneThis session was ended. Sign in again to continue.
auth.sso_requiredNoneThis utility requires sign-in through its identity provider (SSO).
auth.step_up_requiredNoneConfirm your identity to continue.
auth.token_expiredNoneThe code or link has expired. Request a new one.
auth.unauthenticatedNoneYour session has ended. Sign in again.
capability.inactiveNoneThis capability is not active for the utility yet.
cashier.shift_not_openNoneOpen a cash desk shift first.
connection.property_not_ownedNoneThis property does not belong to this customer.
connector.lease_expiredNoneThis job's lease has expired. Try again.
feature.not_configuredNoneThis feature is not set up yet.
file.too_largeNoneThe file exceeds the size limit.
file.type_unsupportedNoneThis file type is not accepted.
identity.password_too_commonNoneThis password is too common. Choose another one.
import.column_missingcolumnThe file is missing the {column} column.
import.file_emptyNoneThe file has no rows to import.
import.file_invalidNoneThe file could not be read. Check its format.
import.line_invalidlineLine {line} of the file is incomplete or not valid.
import.too_many_rowsmaxThe file has too many rows: at most {max} at a time.
integration.bad_gatewayNoneThe external service could not be reached.
integration.conflictNoneThe external service refused the operation because of a conflict.
integration.unavailableNoneThe external service is not available. Try again later.
inventory.insufficient_stockNoneThere is not enough stock in the store.
inventory.item_unavailableNoneItem {item} is not in the catalogue or is inactive.
inventory.whole_units_onlyNone{item} is counted in whole units.
invoice.has_paymentsNoneThis invoice has payments and cannot be voided. Issue a credit note instead.
invoice.no_balanceNoneThis invoice has no balance due.
invoice.not_openNoneThis invoice is not open.
invoice.voidNoneThis invoice is void.
leak_allowance.ineligibleNoneThis invoice does not meet the leak allowance policy.
meter.no_collectorNoneThis meter has no collector to carry commands.
meter.no_reading_baselineNoneNo accepted readings bound the consumption period.
meter.serial_mismatchNoneThe serial number does not match the meter.
payment.method_not_configuredNoneThis payment method is not configured for this utility.
payment.reference_in_useNoneThis reference was already used.
payment.session_mismatchNoneThe payment does not match the payment session.
proof.already_reviewedNoneThis proof was already reviewed.
reading.unit_mismatchNoneThe reading unit does not match the meter unit.
request.cursor_invalidNoneThe requested page is no longer valid. Reload the list.
request.idempotency_conflictNoneThis request was already sent with different details. Reload and try again.
request.invalidNoneThe entered details are not valid. Review them and try again.
request.payload_too_largeNoneThe file is too large.
request.rate_limitedNoneToo many attempts. Wait a moment and try again.
request.timeoutNoneThe request took too long. Try again.
request.unsupportedNoneThis operation is not supported.
resource.already_existsNoneThis record already exists.
resource.conflictNoneThis operation is not possible in the current state of the record.
resource.goneNoneThis address no longer exists.
resource.not_foundNoneRecord not found.
server.internalNoneA server error occurred. Try again in a moment.
state.invalid_transitionNoneThis action is not possible in the current state of the record.
subscription.connection_limit_reachedNoneYour plan allows up to {max} active connections. Change plan to activate more.
subscription.suspendedNoneThis utility subscription is suspended for non-payment. Settle the open invoice to resume making changes.
validation.duplicatefieldSome values are repeated. Each entry must be unique.
validation.end_before_startNoneThe end date must be after the start date.
validation.field_requiredfieldFill in the required fields.
validation.invalid_choicefieldChoose one of the available options.
validation.invalid_formatfieldOne of the values is not in the right format. Review it and try again.
validation.length_out_of_rangefield, min, maxThe text must be between {min} and {max} characters long.
validation.must_be_futurefieldThe date must be in the future.
validation.must_be_positivefieldEnter a value greater than zero.
validation.must_not_be_futurefieldThe date cannot be in the future.
validation.must_not_be_negativefieldThe value cannot be negative.
validation.out_of_rangefield, min, maxThe value must be between {min} and {max}.
validation.reason_requiredfieldEnter a reason.
validation.too_largefield, maxThe value cannot be more than {max}.
validation.too_longfield, maxThe text is too long: use at most {max} characters.
validation.too_manyfield, maxToo many entries: at most {max}.
validation.too_shortfield, minThe text is too short: use at least {min} characters.
validation.too_smallfield, minThe value cannot be less than {min}.
workspace.unavailableNoneThis utility is suspended or closed.