Error Codes Reference

All API errors follow a consistent format. Here is the complete reference.

Error Response Format

{
  "error": {
    "type": "invalid_request",
    "message": "The 'customer_id' field is required.",
    "code": "missing_required_field",
    "param": "customer_id",
    "doc_url": "https://docs.otesse.com/api/errors#missing_required_field"
  }
}

Field	Description
type	Error category
message	Human-readable description
code	Machine-readable error code
param	The specific parameter that caused the error (when applicable)
doc_url	Link to documentation about this error

HTTP Status Codes

Status	Meaning
200	Success
201	Created — resource was successfully created
204	No Content — successful deletion
400	Bad Request — invalid parameters or missing fields
401	Unauthorized — invalid or missing API key/token
403	Forbidden — valid credentials but insufficient permissions
404	Not Found — resource does not exist
409	Conflict — resource already exists or state conflict
422	Unprocessable Entity — valid format but failed validation
429	Too Many Requests — rate limit exceeded
500	Internal Server Error — unexpected error on our side
503	Service Unavailable — temporary outage, retry later

Error Types

authentication_error

The API key or token is invalid, expired, or missing.

{ "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "The API key provided is invalid." } }

Action: Check your API key. Ensure it is not expired or revoked. Verify the Authorization header format.

authorization_error

Valid credentials but insufficient permissions for this action.

{ "error": { "type": "authorization_error", "code": "insufficient_scope", "message": "This API key does not have the 'invoices:write' scope." } }

Action: Check the scopes assigned to your API key. Generate a new key with the required scopes.

invalid_request

The request is malformed or missing required fields.

Common codes:

• missingrequiredfield — A required parameter was not provided
• invalidfieldvalue — A parameter value is not valid (wrong type, out of range)
• invalid_json — Request body is not valid JSON

resourcenotfound

The requested resource does not exist.

{ "error": { "type": "resource_not_found", "code": "booking_not_found", "message": "No booking found with ID 'bk_invalid123'." } }

Action: Verify the resource ID. Check if the resource was deleted.

conflict

The operation conflicts with the current state.

{ "error": { "type": "conflict", "code": "booking_already_cancelled", "message": "This booking has already been cancelled." } }

server_error

An unexpected error on our side. These are rare and we monitor them automatically.

Action: Retry the request after a brief delay. If the error persists, contact support with the X-Request-Id header value from the response.

Error Handling Best Practices

1. Always check the HTTP status code first — Branching on status is faster than parsing the error body
2. Log the full error response — Include the code and message for debugging
3. Use the X-Request-Id header — Include it when contacting support about errors
4. Handle retryable errors — 429 and 503 are temporary; implement retry with backoff
5. Do not retry 4xx errors — These indicate a problem with your request that will not resolve on retry