Errors

When a request fails, the API answers with a non-2xx HTTP status and a JSON body in one shape:

{
  "error": "Permission denied: VIEW_INVOICE required",
  "code": "ACCESS_DENIED"
}

Some refusals carry one more field named in the table below, such as issues for validation errors or requiredPermission for an access-level refusal.

Handle errors in your codeCopy Anchor Link

1. Check the HTTP status first. A 2xx is success; anything else carries the shape above.
2. If the body has a code, branch on it. Codes are the contract; messages are not.
3. If there is no code, act on the status. A few endpoints still answer some 400 and 404 responses without one.
4. On 500, log the errorId so you can report it.

Status codesCopy Anchor Link

Error codesCopy Anchor Link

These codes come from the API's shared error handling, so you can meet them on any endpoint. Individual endpoints add their own codes, such as STAGE_NOT_FOUND on POST /api/leads; the error text explains each one.

A validation error looks like this:

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "issues": [
    {
      "code": "invalid_value",
      "values": ["HOT", "WARM", "COLD"],
      "path": ["temperature"],
      "message": "Invalid option: expected one of \"HOT\"|\"WARM\"|\"COLD\""
    }
  ]
}

A request body that is not valid JSON answers 400 with { "error": "Invalid JSON body" }.

Server faults and errorIdCopy Anchor Link

A 500 means something failed on the APROS side, not in your request. The body never explains the cause; it carries a short ID instead:

{ "error": "Failed to fetch leads", "errorId": "e_3f9a1c" }

The same errorId is written to the server log next to the real cause. To get the fault investigated, write to hello@apri-code.com and include:

• the errorId,
• your workspace address,
• the method and path you called, and roughly when.

You do not need to send your API key or the request body.

Retrying safelyCopy Anchor Link

Retry only what can succeed on a second try:

Retrying a create is risky: if the first request succeeded but its response was lost, a retry creates a second record. To prevent that, send an Idempotency-Key header with a value that is unique for the operation, such as a UUID, and reuse the same value when you retry:

curl -X POST "https://<your-workspace>.apros.app/api/tasks" \
  -H "Authorization: Bearer $APROS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c9a52-8d3e-4b7a-a2f0-9c4d1e8b7a63" \
  -d '{ "title": "Call back Koval Studio" }'

How APROS treats the header:

• Same key, same body: APROS returns the stored response of the first successful request. The operation does not run again.
• Same key, different body: 409 with IDEMPOTENCY_KEY_REUSED. Use a new key for every distinct operation.
• Same key while the first request is still running: 409 with IDEMPOTENCY_KEY_IN_FLIGHT. Nothing was created twice; retry later with the same key.
• After a failure: only successful (2xx) responses are stored. If the first attempt failed, the key is free, and a retry with it runs the operation again.
• Keys are kept for 24 hours and belong to the person the API key belongs to.
• Without the header, the endpoint behaves as usual and does no replay protection.

These endpoints accept Idempotency-Key: