Error Codes

All error responses return a JSON body with a message field. Security-sensitive endpoints return generic messages to prevent information disclosure.

Response Format

json

{
  "message": "Validation failed: phoneNumber must be in E.164 format"
}

Status Codes

Code	Name	Description
400	Bad Request	The request body or parameters are invalid. Check the error message for specifics.
401	Unauthorized	Invalid or missing API key. Check your x-api-key header.
402	Payment Required	The workspace is out of capacity. This is never about key access - an invalid or wrongly scoped key returns 401 or 403. The key stays valid. On an agent-registered workspace a human has not yet claimed, the response carries a claim block naming POST /claim, which mints a one-time link for a person to add capacity; carry on with the same key afterwards.
403	Forbidden	Your key cannot make this request: it is scoped to a different workspace, it lacks the scope the route requires, or you have exceeded your per-minute request rate limit. Rate limiting is enforced in the API Gateway authorizer, which can only deny with 403, so a rate-limited request arrives here rather than as a 429.
404	Not Found	The requested resource does not exist or belongs to a different workspace.
409	Conflict	The request conflicts with the current state (e.g., job already running).
429	Too Many Requests	A concurrency ceiling is full - too many mapping, mission-test or digital-test runs are already in flight for your workspace. Wait for a run to finish and retry. No Retry-After header is sent; per-minute request rate limiting returns 403, not this code.
500	Internal Server Error	An unexpected error occurred. Contact support if the issue persists.

SDK error types

The SDKs raise typed exceptions, so you can either catch by status code or by class. All API error subclasses inherit from NopaqueAPIError and carry status, code, details, and request_id / requestId.

HTTP	Exception class
400	`ValidationError`
401	`AuthenticationError`
403	`PermissionError`
404	`NotFoundError`
409	`ConflictError`
429	`RateLimitError` (carries `retry_after` / `retryAfter`)
5xx	`ServerError`
–	`APIConnectionError` (network failure, including S3 PUT/GET)
–	`APITimeoutError` (request exceeded timeout)

python

from nopaque import Nopaque, NotFoundError, RateLimitError

client = Nopaque()

try:
    job = client.mapping.get("map_does_not_exist")
except NotFoundError as e:
    print(f"Not found: {e.message}, request_id={e.request_id}")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")