Errors

Error response

All errors return a flat JSON object with every field always present:

string

required

Broad error classification. One of: api_error, authentication_error, idempotency_error, invalid_request_error, rate_limit_error.

string

required

Machine-readable error code for programmatic handling. Use this to branch on specific error conditions. Never parse the message field.

string

required

Human-readable description of the error. Not a stable contract. Do not parse or branch on message content.

string | null

required

The request parameter that caused the error, or null if not parameter-specific.

string

required

Link to documentation explaining the error.

string

required

Unique request identifier for tracing and support. Also returned as a Correlation-Id response header on all responses.

Category	Meaning
`api_error`	Server-side failure. You did nothing wrong. Retry may help.
`authentication_error`	Missing or invalid API key.
`idempotency_error`	Idempotency key conflict (reuse with different params).
`invalid_request_error`	Client-side problem: bad parameters, not found, state conflict.
`rate_limit_error`	Too many requests. Back off and retry.

Error codes

Structural codes

Code	Category	HTTP	When
`parameter_invalid`	`invalid_request_error`	400	Request parameter fails validation
`parameter_missing`	`invalid_request_error`	400	Required parameter not provided
`validation_error`	`invalid_request_error`	400	Request body fails schema validation
`api_version_error`	`invalid_request_error`	400	Unknown or unsupported `api-version` header value
`invalid_cursor`	`invalid_request_error`	400	Pagination cursor is malformed or could not be read
`cursor_mismatch`	`invalid_request_error`	400	Pagination cursor was issued for different filters
`idempotency_key_required`	`invalid_request_error`	400	POST request sent without an `Idempotency-Key` header
`authentication_required`	`authentication_error`	401	Missing or invalid API key
`permission_denied`	`invalid_request_error`	403	Valid key, but the request is forbidden by a non-scope check (feature flag, enabled surface, beneficiary allowlist)
`insufficient_scope`	`invalid_request_error`	403	Valid key, but missing one or more scopes the endpoint requires. Carries an additional `required_scopes` array
`resource_not_found`	`invalid_request_error`	404	Resource does not exist
`method_not_allowed`	`invalid_request_error`	405	HTTP method not supported on this endpoint
`conflict`	`invalid_request_error`	409	Business state conflict
`idempotency_key_already_used`	`idempotency_error`	409	Key reuse with different parameters
`request_in_progress`	`idempotency_error`	409	Concurrent request with same key
`payload_too_large`	`invalid_request_error`	413	Request body exceeds the maximum size
`rate_limit_exceeded`	`rate_limit_error`	429	Too many requests
`internal_error`	`api_error`	500	Unexpected server failure
`upstream_error`	`api_error`	500	A required upstream service returned an error

Domain codes

These codes refine invalid_request_error for specific resources. They allow finer-grained handling than the generic parameter_invalid or validation_error.

Code	HTTP	When
`payout_validation_failed`	400	Payout request fails business validation
`conversion_validation_failed`	400	Conversion request fails business validation
`quote_validation_failed`	400	Quote request fails business validation
`invalid_currency`	400	Currency is not supported for the requested action
`account_holder_already_existing`	409	An account holder with the same identity already exists. Carries an additional `existing_holder_id` field

Examples

{
  "category": "invalid_request_error",
  "code": "parameter_missing",
  "message": "The amount parameter is required.",
  "param": "amount",
  "doc_url": "https://docs.augustus.com/v1/errors",
  "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

{
  "category": "invalid_request_error",
  "code": "insufficient_scope",
  "message": "Insufficient scope to perform this operation.",
  "param": null,
  "required_scopes": ["payouts:write"],
  "doc_url": "https://docs.augustus.com/v1/errors",
  "correlation_id": "e5f6a7b8-c9d0-1234-ef01-234567890123"
}

{
  "category": "invalid_request_error",
  "code": "resource_not_found",
  "message": "No payout found with the given ID.",
  "param": null,
  "doc_url": "https://docs.augustus.com/v1/errors",
  "correlation_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

{
  "category": "idempotency_error",
  "code": "idempotency_key_already_used",
  "message": "This idempotency key has already been used with different parameters.",
  "param": null,
  "doc_url": "https://docs.augustus.com/v1/errors",
  "correlation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}

{
  "category": "rate_limit_error",
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after a short delay.",
  "param": null,
  "doc_url": "https://docs.augustus.com/v1/errors",
  "correlation_id": "d4e5f6a7-b8c9-0123-def0-456789012345"
}

{
  "category": "api_error",
  "code": "internal_error",
  "message": "An unexpected error occurred. Please retry or contact support.",
  "param": null,
  "doc_url": "https://docs.augustus.com/v1/errors",
  "correlation_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
}

Getting Started

Resources

Error response

Categories

Error codes

Structural codes

Domain codes

Examples

​Error response

​Categories

​Error codes

​Structural codes

​Domain codes

​Examples

Error response

Categories

Error codes

Structural codes

Domain codes

Examples