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:
| Field | Description |
|---|---|
field | Dotted path to the field that failed, relative to the request body |
issue | Identifies 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 |
message | Human-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"
}
]
}
}
| Field | Description |
|---|---|
resources | Up to 10 resources that explain the error. The field is absent when no safe, useful reference is available. |
resources[].type | Open string naming the resource type. Current values are contact, originator, and payment. |
resources[].id | Opaque resource identifier. |
resourceCount | Total 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 theIdempotency-Keyyou 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
| Code | Meaning | When it happens |
|---|---|---|
400 | Bad Request | Invalid request body or query parameters |
401 | Unauthorized | API key is missing, malformed, unknown, revoked, or expired |
403 | Forbidden | The API key is valid but is not an organization key |
404 | Not Found | Resource does not exist or is not accessible |
409 | Conflict | Operation 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 |
500 | Internal Server Error | Unexpected server-side failure |
503 | Service Unavailable | A 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.
| Code | Cause | What to do |
|---|---|---|
401 | The Authorization header is missing or malformed, or the key is unknown, revoked, or expired | Send Authorization: Bearer <api_key>. Issue a new key if the current one is no longer active |
403 | The key is valid but is not an organization key | Use a key of the form luqra-now.org.{env}.* |
503 | The API key lookup could not reach its database | Retry after a short delay. The request was not processed |
Common error codes
| Code | Status | Description |
|---|---|---|
VALIDATION_ERROR | 400 | Request body or parameters failed schema validation |
INVALID_JSON | 400 | The request body contained the same JSON key more than once. Remove the duplicate key and retry |
IDEMPOTENCY_KEY_REQUIRED | 400 | The Idempotency-Key header was missing, empty, or longer than 255 characters on POST /v1/payments |
UNAUTHORIZED | 401 | API key is missing, malformed, unknown, revoked, or expired |
FORBIDDEN | 403 | The API key is valid but is not an organization key |
NOT_FOUND | 404 | The requested resource was not found |
CONFLICT | 409 | Resource 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_BODY | 409 | An 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_ERROR | 500 | An unexpected error occurred |
SERVICE_UNAVAILABLE | 503 | A 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_UNAVAILABLEmeans the request never reached the banking network -- unlikeINTERNAL_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_DATAorINVALID_CONTACT_DATA-- thefailureMessagenames the offending field. Update the named record, then create a new payment with a freshIdempotency-Key. The sameexternalPaymentIdmay 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 freshIdempotency-Key. If the error persists, contact support.
See the payment lifecycle for full details.
Handling errors
Best practices for error handling:
- Check the
codefield for programmatic error handling rather than parsing the message string. Within a validation error, branch on each detail'sfieldand itsvalidation_*issuefor the same reason - Log the full error response including
detailsandresourcesfor 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-KeyonPOST /v1/paymentsto make retries safe. See Idempotency and Retries.