Errors & Rate Limits

Understand API error responses and rate limiting to build robust integrations.

HTTP Status Codes

The Aryna API uses conventional HTTP response codes to indicate success or failure of requests.

2xx

Success

The request was successful

200 OK201 Created

4xx

Client Errors

The request contains invalid parameters or authorization

400 Bad Request401 Unauthorized403 Forbidden404 Not Found409 Conflict429 Too Many Requests

5xx

Server Errors

Something went wrong on our end

500 Internal Server Error

Error Response Format

All error responses follow a consistent JSON structure for easy parsing.

Error Response Structure

{
  "error": "Validation failed",
  "details": [
    {
      "field": "zipcode",
      "message": "Zipcode must be in format: 12345 or 12345-6789"
    }
  ]
}

Common Error Codes

400

Bad Request

The request was malformed or contains invalid parameters. Check the error details for specific validation failures.

Common Causes:

• Missing required fields
• Invalid field formats (email, URL, zipcode)
• Field values exceed maximum length

401

Unauthorized

Authentication failed. The API key is missing, invalid, or has been revoked.

Solutions:

• Verify your API key is correctly formatted
• Check that the Authorization header is included
• Ensure the API key hasn't been revoked

403

Forbidden

The API key doesn't have the required scope permissions for this endpoint.

Solutions:

• Check which scopes are required for the endpoint
• Create a new API key with the necessary scopes
• Contact an admin to update permissions

404

Not Found

The requested resource doesn't exist or doesn't belong to your account.

Common Causes:

• Invalid resource ID
• Resource has been deleted
• User email not found in account (for assignments)

409

Conflict

The request conflicts with existing data, such as a duplicate unique identifier.

Common Causes:

• Duplicate external_community_id
• Email already invited or registered

429

Too Many Requests

You've exceeded the rate limit. Wait before making additional requests.

Solutions:

• Check the Retry-After header for wait time
• Implement exponential backoff
• Reduce request frequency

500

Internal Server Error

An unexpected error occurred on our servers. If this persists, contact support.

What to do:

• Retry the request after a short delay
• Check our status page for incidents
• Contact support if the issue persists

Rate Limiting

To ensure fair usage and system stability, the API enforces rate limits per API key.

Current Limit

100 requests per minute

This limit applies per API key. All requests count toward this limit, regardless of success or failure.

Rate Limit Headers

Every API response includes headers to help you track your rate limit status:

Header	Description
X-RateLimit-Limit	Maximum requests per minute (100)
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when limit resets
Retry-After	Seconds to wait (only on 429 errors)

Handling Rate Limits

Implement these strategies to avoid hitting rate limits:

1. Monitor Rate Limit Headers

Check the X-RateLimit-Remaining header and slow down requests as you approach the limit.

2. Implement Exponential Backoff

When you receive a 429 response, wait before retrying. Use the Retry-After header value.

3. Batch Operations

Where possible, use pagination with higher limits instead of making many small requests.

4. Cache Responses

Cache API responses when appropriate to reduce the number of requests.

Error Handling Best Practices

Always check HTTP status codes
Don't assume success - check the status code before processing responses
Parse error details
Read the error message and details field for specific information about what went wrong
Implement retry logic
Retry requests that fail due to rate limiting or server errors with exponential backoff
Log errors for debugging
Keep logs of API errors to help diagnose integration issues