Error Handling
API v1 is being deprecated. Use v2 for new integrations. For existing integrations, see the migration guide and API Reference v1.
For v2, classify failures by HTTP status and choose recovery by code. For v1, see
V1 error handling.
Status codes
| Status | Meaning and next step |
|---|---|
200 OK | The request succeeded |
201 Created | The resource was created; v2 project setup may still be running |
204 No Content | The operation succeeded without a response body; do not parse JSON |
400 Bad Request | Correct invalid fields or missing required headers |
401 Unauthorized | Check the key or token, expiration, revocation, and environment |
403 Forbidden | Check user attribution, permissions, resource access, and required capabilities |
404 Not Found | The resource does not exist or is not visible to this caller |
409 Conflict | Inspect the error code and operation-specific recovery instructions |
412 Precondition Failed | V2: read fresh state and reconcile a stale If-Match value |
422 Unprocessable Entity | A required capability is unavailable; check the operation’s prerequisites |
428 Precondition Required | V2: supply the required If-Match header |
429 Too Many Requests | Wait for Retry-After before retrying |
500 Internal Server Error | An unexpected failure; reconcile writes before retrying |
504 Gateway Timeout | The operation timed out; its result may be uncertain |
The reference for each operation lists its responses. See API Reference v2.
Error response format
V2 errors use code, message, and requestId. Validation failures can include
fieldErrors; other errors can carry details.
{
"code": "VALIDATION_ERROR",
"message": "The request is invalid.",
"requestId": "example-request-id",
"fieldErrors": [
{ "field": "address.zipcode", "message": "Required" }
]
}
Branch on code, not the wording of message. Save requestId and the
x-request-id response header for support. Do not put API keys, signing secrets,
or applicant information into diagnostic logs.
Authentication and access
For 401, confirm the credential is active and belongs to the environment being
called. For 403, check the associated user's permissions and resource access.
Organization membership does not grant access to every resource. A 404 can
mean the resource is hidden from the caller, not that its ID is wrong. See
Authentication & API Keys.
Validation and concurrent updates
On 400, correct the payload or header named in the error. For v2 validation,
use fieldErrors to locate the affected fields. A missing idempotency key returns
IDEMPOTENCY_KEY_REQUIRED.
On v2 428 (IF_MATCH_REQUIRED), read the resource and send its ETag with the
write. On 412 (ETAG_MISMATCH), read again and reconcile your change before
retrying. Do not blindly overwrite a concurrent update. See
Concurrent updates.
Design Help returns 422 / UNPROCESSABLE_ENTITY if the organization’s
design-assistance pipeline is disabled. Contact support to enable it; retries cannot.
Conflicts
A 409 is not a guarantee that no work happened. Read the code and details.
| V2 code | Recovery |
|---|---|
IDEMPOTENCY_KEY_CONFLICT | Retry with the original payload, or use a new key for a genuinely new operation |
IDEMPOTENCY_REQUEST_IN_PROGRESS | Wait and retry with the same key; reconcile state if unresolved |
APPLICATION_SUBMISSION_OUTCOME_UNKNOWN | Read the project's financing state before any new submission |
Other conflicts can identify duplicates or resources that are still in use. Follow the operation's recovery instructions rather than repeatedly submitting the same request.
Rate limits
On 429, honor Retry-After. API v2 has both organization and credential
budgets; the error body uses RATE_LIMITED and structured details. See Rate Limits.
Timeouts, network failures, and server errors
Reads can be retried with exponential backoff and jitter. For writes, a missing response does not tell you whether the operation ran:
Where idempotency is supported, reuse the original key and payload. Follow any operation-specific recovery steps, especially for lender submissions. Do not change keys merely to get past a pending or uncertain result.
If the problem persists, contact Artemis with the environment, method, path, time, HTTP status, and v2 request ID. See Idempotency for retry rules.
V1 error handling
V1 errors normally carry a human-readable err message:
{
"err": "Detailed error message describing what went wrong"
}
Authentication-layer rejections use a different shape:
{
"error": "Authentication required",
"code": "UNAUTHENTICATED"
}
Read err for application errors and error for authentication failures.
Validation errors can include a details array:
{
"err": "address.zipcode: Required. address.state: Required",
"details": ["address.zipcode: Required", "address.state: Required"]
}
Additional codes and details vary; follow each operation’s response schema.
For v1 conflicts, read the operation's err, code, and details. Design-help
requests, for example, can conflict with existing open work. Some v1 operations
use 422 for unavailable capabilities; follow their documented responses.
After an uncertain write, read the resource or look up your external reference before retrying. Do not assume v2 idempotency works on v1. See V1 limits and retries.

