Errors

This API uses standard HTTP status codes to indicate success or failure. When a request fails, inspect the HTTP status code first, then review the response body (if present) and any correlation/request IDs returned by your gateway or reverse proxy.

Related sections:

• Authentication: authentication.html
• Pets endpoints: endpoints/pets.html
• Schemas: schemas.html

Common error responses

The following errors are commonly returned by the API (including documented 400, 404, and 500 cases).

Tip: In addition to these, you may also see authentication/authorization failures (often 401/403). See authentication.html for details.

400 Bad Request

When it happens

A 400 typically indicates the server received the request but could not process it due to a client-side issue.

Common examples:

• Malformed JSON (e.g., missing a closing brace)
• Missing required fields in the request body
• Invalid query parameter values (wrong type/format)
• Unsupported values for constrained fields (enums)

Troubleshooting checklist

1. Ensure the request body is valid JSON.

2. Ensure you are sending the right Content-Type header:

   • Content-Type: application/json

3. Verify required fields and types (see schemas.html).

4. Re-check endpoint-specific requirements (see endpoints/pets.html).

Example

Request (invalid JSON)

curl -X POST "https://api.example.com/pets" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"name": "Mochi", "tag": "cat"'

Response (example)

{
  "error": {
    "code": "bad_request",
    "message": "Malformed JSON payload"
  }
}

404 Not Found

When it happens

A 404 indicates the requested resource does not exist (or the path is incorrect).

Common examples:

• Requesting a pet by an ID that is not present
• Using an incorrect URL (missing a path segment)
• Calling the right URL with the wrong HTTP method

Troubleshooting checklist

1. Confirm you’re calling the correct endpoint and method (see endpoints/pets.html).
2. Verify the ID exists by listing resources first (if supported) and then retrieving by ID.
3. Confirm the environment/base URL (dev vs prod).

Example

Request

curl -X GET "https://api.example.com/pets/999999" \
  -H "X-API-Key: YOUR_API_KEY"

Response (example)

{
  "error": {
    "code": "not_found",
    "message": "Pet not found"
  }
}

500 Internal Server Error

When it happens

A 500 indicates an unexpected condition prevented the server from fulfilling the request.

This can be caused by:

• A transient failure in a downstream dependency (database, cache, third-party integration)
• An unhandled server-side exception
• Rare input edge cases

Troubleshooting checklist

1. Retry the request with exponential backoff (especially for idempotent operations like GET).

2. If the error persists, capture:

   • Timestamp (with timezone)
   • Endpoint path + method
   • Request headers (excluding sensitive values)
   • Request body (redact sensitive data)
   • Full response body

3. Contact support and include any correlation/request IDs if returned by your infrastructure.

Example

Response (example)

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  }
}

Handling and retry guidance

Retries

• Safe to retry (generally): GET and other idempotent operations.
• Retry with caution: POST/non-idempotent operations (may create duplicates). If the API supports idempotency keys, use them.

Suggested retry strategy for transient failures:

• Initial delay: 250–500 ms
• Backoff: exponential (e.g., 2x)
• Jitter: add random 0–100 ms
• Max attempts: 3–5

Logging recommendations

Log enough to reproduce and debug without storing secrets:

• HTTP method + path
• Status code
• Latency
• Request ID / correlation ID (if present)
• Sanitized request/response bodies

Frequently seen causes