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

StatusMeaning and next step
200 OKThe request succeeded
201 CreatedThe resource was created; v2 project setup may still be running
204 No ContentThe operation succeeded without a response body; do not parse JSON
400 Bad RequestCorrect invalid fields or missing required headers
401 UnauthorizedCheck the key or token, expiration, revocation, and environment
403 ForbiddenCheck user attribution, permissions, resource access, and required capabilities
404 Not FoundThe resource does not exist or is not visible to this caller
409 ConflictInspect the error code and operation-specific recovery instructions
412 Precondition FailedV2: read fresh state and reconcile a stale If-Match value
422 Unprocessable EntityA required capability is unavailable; check the operation’s prerequisites
428 Precondition RequiredV2: supply the required If-Match header
429 Too Many RequestsWait for Retry-After before retrying
500 Internal Server ErrorAn unexpected failure; reconcile writes before retrying
504 Gateway TimeoutThe 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 codeRecovery
IDEMPOTENCY_KEY_CONFLICTRetry with the original payload, or use a new key for a genuinely new operation
IDEMPOTENCY_REQUEST_IN_PROGRESSWait and retry with the same key; reconcile state if unresolved
APPLICATION_SUBMISSION_OUTCOME_UNKNOWNRead 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.