Errors

The Luqra Now API uses conventional HTTP status codes and returns structured error responses to help you handle failures gracefully.

Error response format

All error responses follow a consistent structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "A human-readable description of the error"
  }
}

Validation errors include additional detail:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "details": [
      {
        "field": "email",
        "issue": "validation_email_required",
        "message": "Enter an email address."
      },
      {
        "field": "legalAddress.postalCode",
        "issue": "validation_postal_code_format",
        "message": "Enter a 5-digit ZIP code."
      }
    ]
  }
}

Each entry in details describes one failed field:

FieldDescription
fieldDotted path to the field that failed, relative to the request body
issueIdentifies the rule that failed. Most rules report a stable validation_* code, which is safe to branch on. Rules that have no code report their description here instead, so treat an issue that is not a validation_* code as informational
messageHuman-readable description of the rule. Wording may change without notice

A field can appear more than once when it fails several rules.

Some 404 and 409 responses identify resources that explain the error:

{
  "error": {
    "code": "CONFLICT",
    "message": "A contact with this name and bank account already exists for this originator",
    "resources": [
      {
        "type": "contact",
        "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
      }
    ]
  }
}
FieldDescription
resourcesUp to 10 resources that explain the error. The field is absent when no safe, useful reference is available.
resources[].typeOpen string naming the resource type. Current values are contact, originator, and payment.
resources[].idOpaque resource identifier.
resourceCountTotal number of safe references when resources is truncated. It is absent when the array is complete.

The error code tells you what a reference points at:

  • NOT_FOUND: the ID from your request that could not be resolved. The reference echoes what you sent and does not confirm whether that ID exists outside your organization.
  • CONFLICT: the existing record your request collides with.
  • IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_BODY: the payment already bound to the Idempotency-Key you sent.

References preserve the order selected by the operation. Empty reference lists are omitted; lists longer than 10 are capped at 10, with resourceCount giving the total safe references, not the preview length. When the list is complete, resourceCount is omitted.

Resolved resource IDs are returned only for records in your organization that the same API key can read. Resource references never include names, account details, or other attributes. Treat type as an open string and ignore values your integration does not recognize.

HTTP status codes

CodeMeaningWhen it happens
400Bad RequestInvalid request body or query parameters
401UnauthorizedAPI key is missing, malformed, unknown, revoked, or expired
403ForbiddenThe API key is valid but is not an organization key
404Not FoundResource does not exist or is not accessible
409ConflictOperation conflicts with current state -- for example, a duplicate contact: the same originator already has a contact with the same name, routing number and account number
500Internal Server ErrorUnexpected server-side failure
503Service UnavailableA dependency is temporarily down -- the API key lookup, or an upstream service such as the bank directory

Errors every endpoint can return

Every /v1 endpoint authenticates the request before the endpoint's own logic runs, so 401, 403, and 503 are possible on all of them regardless of what the endpoint does. The OpenAPI spec declares all three on every operation, so a generated client types them the same way everywhere.

CodeCauseWhat to do
401The Authorization header is missing or malformed, or the key is unknown, revoked, or expiredSend Authorization: Bearer <api_key>. Issue a new key if the current one is no longer active
403The key is valid but is not an organization keyUse a key of the form luqra-now.org.{env}.*
503The API key lookup could not reach its databaseRetry after a short delay. The request was not processed

Common error codes

CodeStatusDescription
VALIDATION_ERROR400Request body or parameters failed schema validation
INVALID_JSON400The request body contained the same JSON key more than once. Remove the duplicate key and retry
IDEMPOTENCY_KEY_REQUIRED400The Idempotency-Key header was missing, empty, or longer than 255 characters on POST /v1/payments
UNAUTHORIZED401API key is missing, malformed, unknown, revoked, or expired
FORBIDDEN403The API key is valid but is not an organization key
NOT_FOUND404The requested resource was not found
CONFLICT409Resource already exists or state conflict. For contacts, the usual cause is that the same originator already has a contact with the same name, routing number and account number. Names compare ignoring letter case and surrounding or repeated whitespace; email plays no part, and two contacts with different names can hold the same bank account. Deleting a contact releases its name and bank account, so the contact you collided with is always one GET /v1/contacts can show you. When safely resolved, error.resources identifies that contact. Updating a contact can also return it when a rename lands on the name of a contact holding the same bank account, or when a concurrent request is changing the same bank account -- only the concurrent case is safe to retry as is. See Managing Contacts
IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_BODY409An Idempotency-Key previously used to create a payment was sent again with a different request body. The bound payment is identified in error.resources. Mint a new key.
INTERNAL_ERROR500An unexpected error occurred
SERVICE_UNAVAILABLE503A dependency is temporarily unavailable -- the API key lookup, or an upstream service such as the bank directory used for routing number validation

Recovering from a 503 SERVICE_UNAVAILABLE

Note -- A 503 SERVICE_UNAVAILABLE means the request never reached the banking network -- unlike INTERNAL_ERROR, it is always safe to retry. No data was written before the dependency was reached, so simply retry the same request after a short delay; when the dependency recovers, the request completes normally.

Recovering from a FAILED payment

A FAILED payment is terminal for that specific payment, but the underlying issue may still be fixable. Branch on the response's failureCode:

  • INVALID_ORIGINATOR_DATA or INVALID_CONTACT_DATA -- the failureMessage names the offending field. Update the named record, then create a new payment with a fresh Idempotency-Key. The same externalPaymentId may be reused so the two attempts tie together in your reporting.
  • INTERNAL_ERROR -- an unexpected error occurred. Wait a few minutes, then create a new payment with a fresh Idempotency-Key. If the error persists, contact support.

See the payment lifecycle for full details.

Handling errors

Best practices for error handling:

  • Check the code field for programmatic error handling rather than parsing the message string. Within a validation error, branch on each detail's field and its validation_* issue for the same reason
  • Log the full error response including details and resources for debugging
  • Retry on 500 errors with exponential backoff (the server may be temporarily unavailable)
  • Do not retry 4xx errors without modifying the request -- these indicate client-side issues
  • Always send an Idempotency-Key on POST /v1/payments to make retries safe. See Idempotency and Retries.