API Errors

Standard error envelope format for consistent error handling.

Every Augno API error uses the same response envelope. The most important fields are code, type, and is_transient: use those fields for programmatic handling instead of parsing the human-readable message.

This page is organized as a quick reference first, then a troubleshooting guide by category. Each error code has a stable anchor, so links like https://docs.augno.com/api/errors#validation_failed open the matching card.

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"
    }
}
FieldTypeHow to use it
codestringExact machine-readable error condition. Branch on this for client behavior.
typestringBroad category: invalid_request_error, api_error, or idempotency_error.
messagestringHuman-readable explanation. Safe to display, but not stable enough to parse.
paramstring | nullOffending request field or parameter when Augno can identify one.
doc_urlstringDocumentation link for this error. Usually follows https://docs.augno.com/api/errors#{code}.
is_transientbooleanWhether retrying the same operation may succeed after a delay.
quotaobject | nullPresent only for limit_exceeded; contains limit, used, and reset_at.
request_log_urlstring | nullDashboard link for the request log when one is available. Include this when contacting Augno support.

Handling Strategy

TypeMeaningDefault action
invalid_request_errorThe request cannot be completed as sent. Examples: bad input, auth, permissions, or not found.Fix the request, credentials, account, or resource state before retrying.
api_errorAugno or a dependency failed while handling a valid request.Retry only when is_transient is true; use exponential backoff and jitter.
idempotency_errorA mutation key is already in use, or the same key was reused with different request parameters.Retry the same operation only for idempotency_in_progress.

For mutating requests, include an idempotency key. If a retry is needed, reuse the same key for the same operation so Augno can avoid duplicate side effects.

Quick Reference

CategoryCodes
Authentication & authorizationexpired_token, api_key_expired, api_key_revoked, invalid_credentials, insufficient_permissions, payment_required
Limitslimit_exceeded, registration_closed
Validationvalidation_failed, missing_field, invalid_format, method_not_allowed
Parametersparameter_missing, parameter_invalid, parameter_unknown, parameters_exclusive
Resourcesresource_not_found, resource_exists, resource_conflict, resource_gone
Idempotencyidempotency_in_progress
Rate limitingrate_limit_exceeded
API versionapi_version_required, api_version_invalid, api_version_too_old
Server errorsinternal_error, service_unavailable, external_service_error, timeout, connection_error, request_timeout, client_closed_request

Troubleshooting Guide

The cards below include a representative request, expected error response, and the recommended fix. Example IDs, API keys, account IDs, and request log URLs are placeholders.

Authentication & Authorization

These errors mean Augno could not authenticate the caller, or the authenticated caller is not allowed to perform the operation. See API Keys for more about API key setup and rotation.

The access or refresh token used for the request has expired. Retrying with the same token will keep failing.

curl API_HOST/v1/catalog/items \
  -H "Authorization: Bearer EXPIRED_ACCESS_TOKEN" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "error": {
        "code": "expired_token",
        "type": "invalid_request_error",
        "message": "Your session has expired. Please sign in again.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#expired_token",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Refresh the token if your client has a refresh flow, or ask the user to sign in again. Server-to-server integrations should rotate to a valid API key.

The API key has passed its configured expiration date.

curl API_HOST/v1/catalog/items \
  -H "Authorization: Bearer augno_expired_key" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "error": {
        "code": "api_key_expired",
        "type": "invalid_request_error",
        "message": "The API key has expired.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#api_key_expired",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Create a new API key, deploy it to the integration, and remove the expired key from secret stores or environment variables.

The API key was explicitly revoked by an administrator or by Augno. Revocation is immediate and permanent.

curl API_HOST/v1/catalog/items \
  -H "Authorization: Bearer augno_revoked_key" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "error": {
        "code": "api_key_revoked",
        "type": "invalid_request_error",
        "message": "The API key has been revoked.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#api_key_revoked",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Generate a replacement key with the required permissions and audit any services that may still be using the revoked key.

The credentials are missing, malformed, unknown, or not valid for the requested flow.

curl API_HOST/v1/catalog/items \
  -H "Authorization: Bearer not_a_real_key" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "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"
    }
}

Check that Authorization uses Bearer, contains the exact API key or token, and matches the account and environment you are targeting.

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

curl -X PATCH API_HOST/v1/identity/account-users/acu_01jmk8h9s4e5m8q7n2v6r3t1pa \
  -H "Authorization: Bearer READ_ONLY_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw" \
  -H "Content-Type: application/json" \
  -d '{"name":"Dana Smith"}'

{
    "error": {
        "code": "insufficient_permissions",
        "type": "invalid_request_error",
        "message": "You do not have permission to perform this action.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#insufficient_permissions",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Use an actor or API key with the required role, grant the missing permission, or verify that Augno-Account points at an account the caller can access.

The target account's subscription is not active enough to continue using the requested operation.

curl API_HOST/v1/catalog/items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_past_due_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "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"
    }
}

Resolve the billing issue in the dashboard, confirm the subscription is active, and retry.

Limits

Limits are plan or registration capacity problems. They are not the same as rate limits.

The account reached a plan-imposed resource limit. The quota object provides the current limit, usage, and optional reset time.

curl -X POST API_HOST/v1/core/sandboxes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw" \
  -H "Content-Type: application/json" \
  -d '{"name":"West Coast Sandbox","mode":"seeded"}'

{
    "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"
    }
}

Delete unused resources, wait until reset_at when present, or upgrade the account's plan.

Public registration has reached capacity for the requested plan or registration flow.

curl -X POST API_HOST/v1/auth/users \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Content-Type: application/json" \
  -d '{"email":"alex@example.com","password":"correct horse battery staple","name":"Alex Chen"}'

{
    "error": {
        "code": "registration_closed",
        "type": "invalid_request_error",
        "message": "Registration for this plan is currently closed.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#registration_closed",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Use another available registration flow, wait for capacity to reopen, or contact Augno support if this plan should accept new registrations.

Validation

Validation errors mean the request body or method is not acceptable for the endpoint.

The request was parsed, but one or more values failed validation or business rules.

curl -X POST API_HOST/v1/auth/users \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Content-Type: application/json" \
  -d '{"email":"not-an-email","password":"correct horse battery staple","name":"Alex Chen"}'

{
    "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"
    }
}

Fix the value named by param, validate request bodies before sending, and retry with corrected input.

A required JSON body field was omitted.

curl -X POST API_HOST/v1/auth/users \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Content-Type: application/json" \
  -d '{"email":"alex@example.com","password":"correct horse battery staple"}'

{
    "error": {
        "code": "missing_field",
        "type": "invalid_request_error",
        "message": "Name is required.",
        "param": "name",
        "doc_url": "https://docs.augno.com/api/errors#missing_field",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Add the required field shown in param. Required fields cannot be cleared with JSON null.

A field is present, but its format does not match what the endpoint accepts.

curl -X POST API_HOST/v1/auth/users \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Content-Type: application/json" \
  -d '{"email":"alex at example dot com","password":"correct horse battery staple","name":"Alex Chen"}'

{
    "error": {
        "code": "invalid_format",
        "type": "invalid_request_error",
        "message": "Email must be a valid email address.",
        "param": "email",
        "doc_url": "https://docs.augno.com/api/errors#invalid_format",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Normalize the field into the format shown in the endpoint reference. Use public type IDs exactly as returned by the API.

The route exists, but does not support the HTTP method you used.

curl -X POST API_HOST/v1/catalog/items/item_01jmk9zr7f6s3n5g8b2q1h4vca \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "error": {
        "code": "method_not_allowed",
        "type": "invalid_request_error",
        "message": "Method not allowed.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#method_not_allowed",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Check the endpoint reference and use an allowed method for that route.

Parameters

Parameter errors are about query string or path parameters. Body field errors use the validation codes above.

A required query string or path parameter was not provided.

curl API_HOST/v1/core/addresses/details/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "error": {
        "code": "parameter_missing",
        "type": "invalid_request_error",
        "message": "Address detail ID is required.",
        "param": "id",
        "doc_url": "https://docs.augno.com/api/errors#parameter_missing",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Include the required path or query parameter and make sure URL construction does not create empty path segments.

A query or path parameter was supplied, but its value is outside the allowed range or enum.

curl "API_HOST/v1/catalog/items?limit=-25" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "error": {
        "code": "parameter_invalid",
        "type": "invalid_request_error",
        "message": "Limit must be greater than zero.",
        "param": "limit",
        "doc_url": "https://docs.augno.com/api/errors#parameter_invalid",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Use the ranges and enum values from the API reference. For pagination, pass back cursors exactly as Augno returned them.

The request included a query parameter the endpoint does not recognize.

curl "API_HOST/v1/catalog/items?skip=50" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "error": {
        "code": "parameter_unknown",
        "type": "invalid_request_error",
        "message": "Unknown parameter: skip.",
        "param": "skip",
        "doc_url": "https://docs.augno.com/api/errors#parameter_unknown",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Remove the unknown parameter or rename it to the supported parameter. Cursor-based list endpoints should use cursor, limit, search, and documented filters.

Two incompatible parameters were both supplied, making the request ambiguous.

curl "API_HOST/v1/catalog/items?cursor=item_01jmk9zr7f6s3n5g8b2q1h4vca&page=2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "error": {
        "code": "parameters_exclusive",
        "type": "invalid_request_error",
        "message": "The cursor and page parameters cannot be used together.",
        "param": "page",
        "doc_url": "https://docs.augno.com/api/errors#parameters_exclusive",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Choose one supported mode for the operation and remove the conflicting parameter.

Resources

Resource errors mean the target object is missing, duplicated, in the wrong state, or gone.

The requested resource does not exist in the target account, or the caller cannot access it.

curl API_HOST/v1/operations/shipping-terms/st_fbv1ygmybo3eauykr74 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "error": {
        "code": "resource_not_found",
        "type": "invalid_request_error",
        "message": "Shipping term not found.",
        "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"
    }
}

Verify the public ID, the Augno-Account header, and whether the resource was deleted. Never send internal database IDs to the API.

The request tried to create a resource that would duplicate an existing unique value.

curl -X POST API_HOST/v1/auth/users \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Content-Type: application/json" \
  -d '{"email":"existing.user@example.com","password":"correct horse battery staple","name":"Existing User"}'

{
    "error": {
        "code": "resource_exists",
        "type": "invalid_request_error",
        "message": "A user with this email already exists.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#resource_conflict",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Find and reuse the existing resource, choose a different unique value, or show a sign-in or recovery path. The current backend links this response to #resource_conflict.

The request conflicts with the current state of the resource or account.

curl -X PATCH API_HOST/v1/operations/shipping-terms/st_default_prepaid \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw" \
  -H "Content-Type: application/json" \
  -d '{"name":"Custom Prepaid"}'

{
    "error": {
        "code": "resource_conflict",
        "type": "invalid_request_error",
        "message": "Default shipping terms cannot be updated.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#resource_conflict",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Refresh the resource, inspect its current state, and submit a valid next action.

The resource existed previously, but has been permanently deleted or can no longer be modified.

curl -X PATCH API_HOST/v1/catalog/products/prod_fbv1ygmybo3eauykr74 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated Product"}'

{
    "error": {
        "code": "resource_gone",
        "type": "invalid_request_error",
        "message": "This product has already been deleted and can no longer be modified.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#resource_gone",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Remove the deleted resource from local caches and create a replacement resource if needed.

Idempotency

Idempotency errors only apply to mutating requests that use an idempotency key. See Idempotency for the full retry model.

A request with the same idempotency key is already being processed.

curl -X PATCH API_HOST/v1/operations/shipping-terms/st_01jmk8q7n2v6r3t1pah9s4e5m8 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw" \
  -H "Idempotency-Key: req_abc123" \
  -H "Content-Type: application/json" \
  -d '{"name":"Collect"}'

{
    "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"
    }
}

Retry the same request with the same key after a short delay. Do not generate a new key unless you intend to start a separate operation.

If the same key is reused with different parameters, Augno returns validation_failed with type: "idempotency_error":

{
    "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"
    }
}

For the non-transient mismatch case, resend the original request exactly or use a new key for the new operation.

Rate Limiting

Rate limiting is temporary throttling. See Rate Limiting for guidance on request pacing.

The caller sent requests faster than Augno allows for the current key, actor, account, or endpoint.

curl API_HOST/v1/catalog/items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "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"
    }
}

Back off before retrying, honor Retry-After when present, and add client-side queueing or rate limiting if your integration bursts above the limit.

API Version

API version errors are fixed by sending a supported Augno-Version header. See API Versioning for supported versions and upgrade guidance.

The request did not include the required Augno-Version header.

curl API_HOST/v1/catalog/items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "error": {
        "code": "api_version_required",
        "type": "invalid_request_error",
        "message": "The Augno-Version header is required. Please include a valid API version. The latest version is CURRENT_API_VERSION.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#api_version_required",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Add Augno-Version to every request or configure it once in your SDK client.

The Augno-Version header is present, but the value is not recognized.

curl API_HOST/v1/catalog/items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: 1900-01-01" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "error": {
        "code": "api_version_invalid",
        "type": "invalid_request_error",
        "message": "Invalid API version '1900-01-01'. Supported versions: [CURRENT_API_VERSION]",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#api_version_invalid",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Use one of the supported versions from the error message or versioning guide.

The endpoint requires a newer API version than the one sent in Augno-Version.

curl API_HOST/v1/operations/shipping-terms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: 2024-01-01" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "error": {
        "code": "api_version_too_old",
        "type": "invalid_request_error",
        "message": "This endpoint requires API version CURRENT_API_VERSION or newer. You requested 2024-01-01.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#api_version_too_old",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Upgrade the version for this integration after testing compatibility.

Server Errors

Server errors mean Augno or a dependency failed while handling the request. Most are transient. For mutating requests, retry with the same idempotency key.

Augno encountered an unexpected server-side failure. The public message is intentionally generic; internal diagnostics are captured in Augno logs.

curl API_HOST/v1/catalog/items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "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"
    }
}

Retry with exponential backoff if the operation is safe to retry. If it persists, include request_log_url when contacting Augno support.

An Augno service or internal dependency needed for the request is temporarily unavailable.

curl API_HOST/v1/catalog/items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "error": {
        "code": "service_unavailable",
        "type": "api_error",
        "message": "Service temporarily unavailable.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#service_unavailable",
        "is_transient": true,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Retry after a short delay. If the condition persists, check Augno status information or contact support with request log details.

A third-party service used by Augno returned an error.

curl "API_HOST/v1/core/addresses/suggestions?search=500%20Market%20Street" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "error": {
        "code": "external_service_error",
        "type": "api_error",
        "message": "A downstream provider returned an error.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#external_service_error",
        "is_transient": true,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Retry with backoff. If one provider-specific workflow keeps failing, include the request log URL when reporting it.

The operation exceeded a deadline while Augno was waiting for work to finish.

curl -X POST API_HOST/v1/sales/sales-orders/so_01jmk9zr7f6s3n5g8b2q1h4vca/actions/create-production-run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw" \
  -H "Idempotency-Key: req_create_run_01"

{
    "error": {
        "code": "timeout",
        "type": "api_error",
        "message": "The operation timed out.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#timeout",
        "is_transient": true,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Retry with exponential backoff. For mutations, reuse the same idempotency key.

Augno could not establish or maintain a network connection to a service needed for the request.

curl API_HOST/v1/operations/shipping-terms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw"

{
    "error": {
        "code": "connection_error",
        "type": "api_error",
        "message": "Could not connect to a downstream service.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#connection_error",
        "is_transient": true,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Retry after a short delay. If it persists, treat the affected workflow as unavailable.

The overall request exceeded its deadline before Augno could finish processing.

curl -X POST API_HOST/v1/catalog/items/actions/bulk-create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw" \
  -H "Idempotency-Key: req_bulk_items_01" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"name":"Example Item","type":"product"}]}'

{
    "error": {
        "code": "request_timeout",
        "type": "api_error",
        "message": "Request timed out.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#request_timeout",
        "is_transient": true,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Retry with backoff. For long-running or bulk operations, keep payloads reasonable and use idempotency keys.

The client disconnected before Augno finished processing the request. Status 499 is a non-standard HTTP status commonly used by proxies for client-closed requests.

curl -X POST API_HOST/v1/catalog/items/actions/bulk-reconcile \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: CURRENT_API_VERSION" \
  -H "Augno-Account: acct_01jmk7x2q9n9h8a4v0r3p6t2yw" \
  -H "Idempotency-Key: req_reconcile_01" \
  -H "Content-Type: application/json" \
  -d '{"items":[]}'

{
    "error": {
        "code": "client_closed_request",
        "type": "api_error",
        "message": "Client closed request.",
        "param": null,
        "doc_url": "https://docs.augno.com/api/errors#client_closed_request",
        "is_transient": false,
        "quota": null,
        "request_log_url": "https://augno.com/dashboard/request-logs/rq_fbv1ygmybo3eauykr74"
    }
}

Investigate client-side cancellation, browser navigation, network interruption, proxy timeout settings, or request timeout settings. For mutations, use idempotency keys before retrying from the client.

Retry Behavior

Errors with "is_transient": true may resolve on retry:

TypeTransient codes
api_errorinternal_error, service_unavailable, external_service_error, timeout, connection_error, request_timeout
idempotency_erroridempotency_in_progress
invalid_request_errorrate_limit_exceeded

Notable non-transient errors:

  • client_closed_request: the server cannot retry for a disconnected client.
  • resource_conflict: the client must resolve the conflicting state.
  • validation_failed with type: "idempotency_error": the key was reused with different parameters.