API Errors

Every error returned by the Augno API uses a consistent envelope and includes a machine-readable code so clients can handle errors programmatically without parsing human-readable messages.

Error Envelope

All error responses are wrapped in an error object:

{
    "error": {
        "code": "validation_failed",
        "type": "invalid_request_error",
        "message": "The email address is not valid.",
        "param": "email",
        "doc_url": "https://docs.augno.com/api/errors#validation_failed",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Fields

quota Object

Present (non-null) only when code is limit_exceeded.

Error Types

Error Codes

Authentication & Authorization — See API Keys

expired_token

JWT access or refresh token has expired. The client should obtain a new token pair using their refresh token or re-authenticate.

api_key_expired

API key has passed its expiration date. Generate a new API key to continue making requests.

api_key_revoked

API key was explicitly revoked by the owner or Augno. Generate a new API key to continue making requests.

invalid_credentials

The provided credentials are incorrect. Verify the email/password or API key and try again.

insufficient_permissions

The caller is authenticated but lacks the required role or permission for this operation.

payment_required

The account's subscription is in a non-active state (past due, canceled, or unpaid). Resolve the billing issue before continuing.

Limits

limit_exceeded

A plan-imposed resource limit has been reached (e.g. maximum sandbox accounts). The response includes a quota object with the current limit, usage, and optional reset time. Upgrade the plan to increase the limit.

registration_closed

Public registration capacity has been reached for the requested plan code. Distinct from limit_exceeded, which applies to per-account resource quotas.

Validation

validation_failed

General input validation failure. Check the message and param fields for details on what needs to be corrected.

missing_field

A required field was not provided in the request body. The param field indicates which field is missing.

invalid_format

A field value does not match the expected format (e.g. invalid email address). The param field indicates which field is invalid.

method_not_allowed

The HTTP method is not supported for this endpoint. Check the API reference for allowed methods.

Parameters

parameter_missing

A required query or path parameter was not provided. The param field indicates which parameter is missing.

parameter_invalid

A parameter value is not valid (e.g. negative limit, out-of-range value). The param field indicates which parameter is invalid.

parameter_unknown

An unrecognized parameter was sent in the request. The param field indicates which parameter is unknown.

parameters_exclusive

Two mutually exclusive parameters were both provided. The param field indicates the conflicting parameter.

Resources

resource_not_found

The requested resource does not exist. Verify the resource ID and try again.

resource_exists

A resource with the same unique constraint already exists (e.g. duplicate email address).

resource_conflict

A state conflict prevents the operation (e.g. optimistic locking failure, concurrent update). The client must resolve the conflict before retrying.

resource_gone

The resource existed but has been permanently deleted. This is not a temporary condition.

Idempotency — See Idempotency

idempotency_in_progress

A request with the same idempotency key is currently being processed. Retry after a short delay.

Note: Reusing an idempotency key with different request parameters returns validation_failed with type idempotency_error.

Rate Limiting — See Rate Limiting

rate_limit_exceeded

The caller has exceeded the allowed request rate. Back off and retry after the duration indicated by the Retry-After header.

API Version — See API Versioning

api_version_required

The Augno-Version header is missing from the request. Include a valid API version in the header.

api_version_invalid

The requested API version string is not recognized. Check the message field for the list of supported versions.

api_version_too_old

The requested API version is below the minimum supported by the endpoint. Upgrade to a newer API version.

Server Errors

internal_error

An unexpected server-side failure occurred. This is generally transient and safe to retry.

service_unavailable

A downstream service is temporarily unreachable. Retry after a short delay.

external_service_error

A third-party dependency returned an error. This is generally transient and safe to retry.

timeout

The operation exceeded its deadline. Retry with exponential backoff.

connection_error

A network-level failure occurred when connecting to a downstream service. Retry after a short delay.

request_timeout

The overall request exceeded its deadline. Retry with exponential backoff.

client_closed_request

The client disconnected before the server finished processing. The server cannot meaningfully retry on behalf of a disconnected client.

Transient Errors

Errors with "is_transient": true represent temporary conditions that may resolve on retry. The combination of code and type determines transience:

Notably not transient:

• client_closed_request — the server cannot meaningfully retry on behalf of a disconnected client.
• resource_conflict — represents a state conflict (e.g. duplicate username) that requires client-side resolution.

Examples

Validation Error (400)

{
    "error": {
        "code": "validation_failed",
        "type": "invalid_request_error",
        "message": "The email address is not valid.",
        "param": "email",
        "doc_url": "https://docs.augno.com/api/errors#validation_failed",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Authentication Error (401)

{
    "error": {
        "code": "invalid_credentials",
        "type": "invalid_request_error",
        "message": "The provided credentials are incorrect.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#invalid_credentials",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Payment Required (402)

{
    "error": {
        "code": "payment_required",
        "type": "invalid_request_error",
        "message": "Your subscription is past due. Please update your payment method to continue.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#payment_required",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Limit Exceeded (403)

{
    "error": {
        "code": "limit_exceeded",
        "type": "invalid_request_error",
        "message": "You have reached the maximum number of sandbox accounts for your plan.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#limit_exceeded",
        "is_transient": false,
        "quota": {
            "limit": 5,
            "used": 5,
            "reset_at": null
        },
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Resource Not Found (404)

{
    "error": {
        "code": "resource_not_found",
        "type": "invalid_request_error",
        "message": "No account found with that ID.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#resource_not_found",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Idempotency In Progress (409)

{
    "error": {
        "code": "idempotency_in_progress",
        "type": "idempotency_error",
        "message": "Request for the idempotency key 'req_abc123' is already being processed.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#idempotency_in_progress",
        "is_transient": true,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Idempotency Key Reuse (400)

{
    "error": {
        "code": "validation_failed",
        "type": "idempotency_error",
        "message": "Idempotency key 'req_abc123' was used with different request parameters; use a new key.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#validation_failed",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Rate Limited (429)

{
    "error": {
        "code": "rate_limit_exceeded",
        "type": "invalid_request_error",
        "message": "Too many requests. Please wait before trying again.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#rate_limit_exceeded",
        "is_transient": true,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Server Error (500)

{
    "error": {
        "code": "internal_error",
        "type": "api_error",
        "message": "Something went wrong.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#internal_error",
        "is_transient": true,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}