Skip to main content

Error Handling

The Rewind Public API uses RFC 7807 Problem Details for consistent error responses. This provides structured, machine-readable error information that makes it easier to handle errors programmatically.

Error Response Format​

All error responses follow the RFC 7807 standard:

{
  "title": "Resource not found.",
  "status": 404,
  "request_id": "req_abc123def456",
  "detail": "The requested account was not found or you don't have access",
  "instance": "/api/v1/accounts/acc_invalid123"
}

Error Response Fields​

  • type (optional): URI identifying the error type
  • title: Human-readable error summary
  • status: HTTP status code
  • request_id: Unique identifier for debugging and support
  • detail (optional): Human-readable error explanation
  • instance (optional): URI identifying the specific request

Common HTTP Status Codes​

400 Bad Request​

Invalid request format or parameters.

{
  "title": "Bad Request",
  "status": 400,
  "request_id": "req_123",
  "detail": "Invalid cursor provided",
  "instance": "/api/v1/accounts"
}

Common causes:

  • Malformed cursor tokens
  • Invalid query parameter values
  • Missing required parameters

401 Unauthorized​

Missing or invalid authentication credentials.

{
  "title": "Unauthenticated",
  "status": 401,
  "request_id": "req_123",
  "instance": "/api/v1/accounts"
}

Common causes:

  • Missing X-API-Key header
  • Invalid or expired API key
  • Malformed authentication header

403 Forbidden​

Valid authentication but insufficient permissions.

{
  "title": "You are not authorized to perform this action.",
  "status": 403,
  "request_id": "req_123",
  "detail": "Access denied to the requested resource",
  "instance": "/api/v1/accounts/acc_123"
}

Common causes:

  • Attempting to access resources outside your organization
  • Insufficient user permissions
  • Account-specific access restrictions

404 Not Found​

The requested resource doesn't exist or isn't accessible.

{
  "title": "Resource not found.",
  "status": 404,
  "request_id": "req_123",
  "instance": "/api/v1/nonexistent"
}

Common causes:

  • Invalid endpoint URLs
  • Non-existent resource IDs
  • Resources outside your organization scope

422 Unprocessable Entity​

Valid request format but invalid data (e.g., invalid account ID format).

{
  "title": "Unprocessable Entity",
  "status": 422,
  "request_id": "req_123",
  "detail": "Invalid account ID format",
  "instance": "/api/v1/accounts/invalid_id"
}

Common causes:

  • Invalid account ID format (must be acc_ followed by 16 alphanumeric characters)

429 Too Many Requests​

You've exceeded a rate limit. Slow down and retry after the indicated interval.

{
  "title": "Too Many Requests",
  "status": 429,
  "request_id": "req_123"
}

Rate limits:

  • Each API key has a per-second request quota; requests above it receive a 429. Your current allowance is returned in the X-RateLimit-Limit header (see below) — read it rather than hard-coding a value, as the quota may change.
  • The API may also return a 429 that isn't tied to your key's own allowance — for example under exceptional aggregate load, or other protective limits. Handle any 429 the same way.

Rate-limit headers (returned on responses governed by your per-key allowance):

  • X-RateLimit-Limit — your per-second request allowance
  • X-RateLimit-Remaining — requests remaining in the current window
  • X-RateLimit-Reset — Unix time (seconds) at which the window resets
  • Retry-After — seconds to wait before retrying (present on a 429)

When present, these headers describe your key's own allowance; they don't necessarily explain why a particular 429 occurred, and they're not returned on 429s that aren't tied to your key's allowance.

How to handle a 429:

  • If Retry-After is present, wait that many seconds before retrying.
  • If it's absent, back off exponentially — e.g. 1s, 2s, 4s, 8s with a little random jitter — before retrying.
  • Don't treat the absence of 429 responses as proof you're under the limit; stay within your budget regardless.

500 Internal Server Error​

Unexpected server error.

{
  "title": "Internal Server Error",
  "status": 500,
  "request_id": "req_123",
  "detail": "An unexpected error occurred.",
  "instance": "/api/v1/accounts"
}

When this occurs:

  • Contact support with the request_id
  • Implement retry logic with exponential backoff
  • Check the status page for known issues

Debugging Tips​

Include the request_id When Contacting Support​

The request_id helps our support team quickly locate and diagnose issues.

Check API Key Validity​

Test your API key with the token endpoint:

curl "https://developer.rewind.com/api/v1/token" \
  -H "X-API-Key: YOUR_API_KEY"

Review Audit Logs​

Check your organization's audit logs for authentication and access issues.