# Erros da API

```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"
    }
  ]
}
```

## Códigos gerais (code)

- `INVALID_REQUEST` (400): The request was malformed or failed validation.
- `UNAUTHORIZED` (401): Authentication is missing, invalid, or expired.
- `FORBIDDEN` (403): The authenticated caller lacks permission for this action.
- `CAPABILITY_INACTIVE` (403): The tenant capability required for this operation is not active.
- `NOT_FOUND` (404): The requested resource does not exist or is not visible in this context.
- `CONFLICT` (409): The request conflicts with the current resource state or an idempotency key.
- `UNSUPPORTED_OPERATION` (400): The requested operation is not supported for this resource.
- `INTEGRATION_UNAVAILABLE` (503): A downstream connector or integration is temporarily unavailable.
- `EXTERNAL_RESOURCE_CONFLICT` (409): An external integration reported a state conflict.
- `RATE_LIMITED` (429): The caller exceeded its request budget; retry after RateLimit-Reset.
- `DEADLINE_EXCEEDED` (504): The operation timed out before completion.
- `INTERNAL_ERROR` (500): An unexpected server error occurred.

## Códigos específicos (error_code)

- `account.contact_in_use`: An account already uses this email or phone.
- `account.creation_review_required`: This account needs a manual review before it can be created. Contact support to continue.
- `account.limit_reached`: This person has reached the allowed number of accounts.
- `account_link.details_required`: Enter the link code, or the utility, the contract or meter number, and the mobile phone.
- `account_link.permission_not_delegable`: This permission cannot be delegated.
- `approval.self_approval`: You cannot approve a request you made.
- `auth.challenge_failed`: We could not confirm you are not a robot. Try again.
- `auth.challenge_required`: Confirm you are not a robot and try again.
- `auth.forbidden`: You do not have permission for this action.
- `auth.invalid_credentials`: The sign-in details are incorrect.
- `auth.ip_not_allowed`: Your utility does not allow access from this network.
- `auth.mfa_challenge_invalid`: The verification request expired. Sign in again.
- `auth.mfa_enrollment_required`: Your utility requires two-factor verification. Enable it in Security to continue.
- `auth.mfa_locked`: Too many incorrect codes. Wait a few minutes and try again.
- `auth.session_ended`: This session was ended. Sign in again to continue.
- `auth.sso_required`: This utility requires sign-in through its identity provider (SSO).
- `auth.step_up_required`: Confirm your identity to continue.
- `auth.token_expired`: The code or link has expired. Request a new one.
- `auth.unauthenticated`: Your session has ended. Sign in again.
- `capability.inactive`: This capability is not active for the utility yet.
- `cashier.shift_not_open`: Open a cash desk shift first.
- `connection.property_not_owned`: This property does not belong to this customer.
- `connector.lease_expired`: This job's lease has expired. Try again.
- `feature.not_configured`: This feature is not set up yet.
- `file.too_large`: The file exceeds the size limit.
- `file.type_unsupported`: This file type is not accepted.
- `identity.password_too_common`: This password is too common. Choose another one.
- `import.column_missing`: The file is missing the {column} column.
- `import.file_empty`: The file has no rows to import.
- `import.file_invalid`: The file could not be read. Check its format.
- `import.line_invalid`: Line {line} of the file is incomplete or not valid.
- `import.too_many_rows`: The file has too many rows: at most {max} at a time.
- `integration.bad_gateway`: The external service could not be reached.
- `integration.conflict`: The external service refused the operation because of a conflict.
- `integration.unavailable`: The external service is not available. Try again later.
- `inventory.insufficient_stock`: There is not enough stock in the store.
- `inventory.item_unavailable`: Item {item} is not in the catalogue or is inactive.
- `inventory.whole_units_only`: {item} is counted in whole units.
- `invoice.has_payments`: This invoice has payments and cannot be voided. Issue a credit note instead.
- `invoice.no_balance`: This invoice has no balance due.
- `invoice.not_open`: This invoice is not open.
- `invoice.void`: This invoice is void.
- `leak_allowance.ineligible`: This invoice does not meet the leak allowance policy.
- `meter.no_collector`: This meter has no collector to carry commands.
- `meter.no_reading_baseline`: No accepted readings bound the consumption period.
- `meter.serial_mismatch`: The serial number does not match the meter.
- `organization.owner_consent_required`: The owner's consent is required.
- `payment.method_not_configured`: This payment method is not configured for this utility.
- `payment.reference_in_use`: This reference was already used.
- `payment.session_mismatch`: The payment does not match the payment session.
- `proof.already_reviewed`: This proof was already reviewed.
- `reading.unit_mismatch`: The reading unit does not match the meter unit.
- `request.cursor_invalid`: The requested page is no longer valid. Reload the list.
- `request.idempotency_conflict`: This request was already sent with different details. Reload and try again.
- `request.invalid`: The entered details are not valid. Review them and try again.
- `request.payload_too_large`: The file is too large.
- `request.rate_limited`: Too many attempts. Wait a moment and try again.
- `request.timeout`: The request took too long. Try again.
- `request.unsupported`: This operation is not supported.
- `resource.already_exists`: This record already exists.
- `resource.conflict`: This operation is not possible in the current state of the record.
- `resource.gone`: This address no longer exists.
- `resource.not_found`: Record not found.
- `server.internal`: A server error occurred. Try again in a moment.
- `state.invalid_transition`: This action is not possible in the current state of the record.
- `subscription.connection_limit_reached`: Your plan allows up to {max} active connections. Change plan to activate more.
- `subscription.suspended`: This utility subscription is suspended for non-payment. Settle the open invoice to resume making changes.
- `validation.duplicate`: Some values are repeated. Each entry must be unique.
- `validation.end_before_start`: The end date must be after the start date.
- `validation.field_required`: Fill in the required fields.
- `validation.invalid_choice`: Choose one of the available options.
- `validation.invalid_format`: One of the values is not in the right format. Review it and try again.
- `validation.length_out_of_range`: The text must be between {min} and {max} characters long.
- `validation.must_be_future`: The date must be in the future.
- `validation.must_be_positive`: Enter a value greater than zero.
- `validation.must_not_be_future`: The date cannot be in the future.
- `validation.must_not_be_negative`: The value cannot be negative.
- `validation.out_of_range`: The value must be between {min} and {max}.
- `validation.reason_required`: Enter a reason.
- `validation.too_large`: The value cannot be more than {max}.
- `validation.too_long`: The text is too long: use at most {max} characters.
- `validation.too_many`: Too many entries: at most {max}.
- `validation.too_short`: The text is too short: use at least {min} characters.
- `validation.too_small`: The value cannot be less than {min}.
- `workspace.unavailable`: This utility is suspended or closed.
