Error Handling

Oproto APIs use standard HTTP status codes and return consistent error responses to help you diagnose and handle issues.

Error Response Format

All errors return a JSON response with the following structure:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested company could not be found",
    "details": {
      "resourceType": "Company",
      "resourceId": "comp_abc123"
    },
    "requestId": "req_7f8g9h0i1j2k"
  }
}

Field	Description
code	Machine-readable error code
message	Human-readable description
details	Additional context (when available)
requestId	Unique identifier for support requests

---

HTTP Status Codes

Success Codes

Status	Meaning
200 OK	Request succeeded
201 Created	Resource created successfully
204 No Content	Request succeeded, no response body

Client Error Codes

Status	Meaning	Common Causes
400 Bad Request	Invalid request format	Malformed JSON, missing required fields
401 Unauthorized	Authentication failed	Missing or invalid access token
403 Forbidden	Access denied	Insufficient permissions for this resource
404 Not Found	Resource doesn't exist	Invalid ID or deleted resource
409 Conflict	Resource conflict	Duplicate entry, version mismatch
422 Unprocessable Entity	Validation failed	Invalid field values
429 Too Many Requests	Rate limit exceeded	See Rate Limiting

Server Error Codes

Status	Meaning	Action
500 Internal Server Error	Unexpected error	Retry with backoff, contact support if persistent
502 Bad Gateway	Upstream service error	Retry with backoff
503 Service Unavailable	Service temporarily down	Retry with backoff
504 Gateway Timeout	Request timed out	Retry with backoff

---

Error Codes Reference

Authentication Errors

Code	Description
INVALID_TOKEN	Access token is malformed or expired
TOKEN_EXPIRED	Access token has expired
INSUFFICIENT_SCOPE	Token lacks required permissions
INVALID_CREDENTIALS	Client credentials are invalid

Validation Errors

Code	Description
VALIDATION_ERROR	One or more fields failed validation
MISSING_REQUIRED_FIELD	A required field was not provided
INVALID_FIELD_VALUE	Field value doesn't match expected format
FIELD_TOO_LONG	Field exceeds maximum length

Resource Errors

Code	Description
RESOURCE_NOT_FOUND	The requested resource doesn't exist
RESOURCE_ALREADY_EXISTS	A resource with this identifier already exists
RESOURCE_DELETED	The resource has been deleted
RESOURCE_LOCKED	The resource is locked and cannot be modified

Rate Limiting Errors

Code	Description
RATE_LIMIT_EXCEEDED	Too many requests in the time window
QUOTA_EXCEEDED	Monthly/daily quota has been reached

---

Handling Errors

Example Error Handler

async function apiRequest(url, options) {
  const response = await fetch(url, options);
  
  if (!response.ok) {
    const error = await response.json();
    
    switch (response.status) {
      case 401:
        // Token expired - refresh and retry
        await refreshToken();
        return apiRequest(url, options);
      
      case 429:
        // Rate limited - wait and retry
        const retryAfter = response.headers.get('Retry-After') || 60;
        await sleep(retryAfter * 1000);
        return apiRequest(url, options);
      
      case 500:
      case 502:
      case 503:
      case 504:
        // Server error - retry with exponential backoff
        throw new RetryableError(error);
      
      default:
        throw new ApiError(error);
    }
  }
  
  return response.json();
}

Retry Strategy

For transient errors (5xx status codes), implement exponential backoff:

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (!error.retryable || attempt === maxRetries - 1) {
        throw error;
      }
      
      const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
      await sleep(delay + Math.random() * 1000);
    }
  }
}

---

Debugging Tips

1. Check the requestId — Include this when contacting support
2. Review the details object — Often contains specific field-level errors
3. Verify your authentication — Most 401/403 errors are token-related
4. Check rate limit headers — Monitor your usage before hitting limits

Getting Help

If you encounter persistent errors:

1. Note the requestId from the error response
2. Check the API Status Page for any ongoing incidents
3. Contact support with the request ID and reproduction steps