Errors

HTTP Status Codes

Code	Meaning	When It Occurs
`200`	OK	Successful request
`201`	Created	Resource created (registration)
`400`	Bad Request	Validation error, missing parameters, invalid data
`401`	Unauthorized	Missing/invalid/expired token, invalid credentials, invalid webhook signature
`403`	Forbidden	Insufficient OAuth scopes, sandbox not enabled
`404`	Not Found	Resource not found
`409`	Conflict	Duplicate event (webhook idempotency), email already registered
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server error

OAuth Errors (RFC 6749)

OAuth-related errors follow the RFC 6749 format:

{
  "error": "invalid_grant",
  "error_description": "Authorization code expired"
}

Error Codes

Error Code	HTTP Status	Description	Common Cause
`invalid_request`	400	Missing or invalid parameters	Missing `client_id`, `redirect_uri`, or `grant_type`
`invalid_grant`	401	Invalid authorization code, expired code, or invalid refresh token	Code used more than once, code expired (5-minute TTL), refresh token expired (30 days)
`invalid_client`	401	Invalid `client_id` or `client_secret`	Wrong credentials, secret was regenerated
`access_denied`	403	Merchant denied authorization	User clicked "Deny" on the consent screen
`server_error`	500	Internal server error	Unexpected server-side issue

Handling OAuth Errors

Authorization callback errors -- If the merchant denies consent or an error occurs during authorization, your redirect_uri receives error parameters:

https://yourmarketplace.com/oauth/callback
  ?error=access_denied
  &error_description=User+denied+authorization
  &state=random_csrf_token_123

Token exchange errors -- Returned as JSON in the response body:

{
  "error": "invalid_grant",
  "error_description": "Authorization code expired"
}

Token refresh errors -- When a refresh token has expired:

{
  "error": "invalid_grant",
  "error_description": "Refresh token expired"
}

When you receive invalid_grant on a refresh attempt, the merchant must re-authorize through the OAuth flow.

API Errors

API endpoints return structured error responses with a consistent format:

Simple Error

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Validation Error with Field Details

{
  "statusCode": 400,
  "message": [
    "salesPerformance.gmv30Days must not be less than 0",
    "revenueConsistency.revenueConcentration must not be greater than 100"
  ],
  "error": "Bad Request"
}

The message field can be either a string or an array of strings. When it is an array, each entry describes a specific field-level validation failure.

Common API Error Scenarios

Scenario	Status	Error	Message
Missing Authorization header	401	Unauthorized	Missing or invalid token
Expired access token	401	Unauthorized	Token expired
Insufficient scope	403	Forbidden	Insufficient scope for this operation
Invalid merchant ID	404	Not Found	Merchant not found
Invalid loan ID	404	Not Found	Loan not found or does not belong to this marketplace
Missing required field	400	Bad Request	Field-specific validation message
Invalid field value	400	Bad Request	Field-specific validation message
Bulk batch too large	400	Bad Request	Maximum 1000 merchants per batch
Data timestamp too old	400	Bad Request	dataTimestamp must be within the last 30 days

Webhook Errors

Inbound Webhook Errors (Your Webhooks to OpenSylo)

Scenario	Status	Description
Missing `X-Marketplace-Signature` header	401	Signature header is required
Invalid HMAC signature	401	Signature does not match
Timestamp outside 5-minute window	401	Timestamp too old or too far in the future
Missing `X-Marketplace-Id` header	401	Marketplace ID header is required
Unknown marketplace ID	401	Marketplace not found
Duplicate `X-Marketplace-Event-Id`	409	Event already processed (idempotency)

Outbound Webhook Failures (OpenSylo Webhooks to You)

When OpenSylo sends webhooks to your endpoint and receives a non-2xx response, it retries with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	24 hours

After 6 failed attempts, the webhook is marked as failed. Ensure your webhook endpoint:

Returns a 2xx status code to acknowledge receipt

Responds within 30 seconds

Handles duplicate deliveries idempotently (check event_id)

Rate Limit Errors

Scenario	Status	Description
Webhook rate limit exceeded	429	Too many requests -- maximum 100 per 60 seconds per marketplace

When rate-limited, the response includes a Retry-After header indicating seconds to wait before retrying.

Response:

{
  "statusCode": 429,
  "message": "Too many requests. Please retry after the specified time.",
  "error": "Too Many Requests"
}

Error Handling Best Practices

Always check HTTP status codes before parsing response bodies. A 2xx status means success; anything else is an error.

Handle token expiry gracefully. When you receive a 401 on an API call, attempt a token refresh. If the refresh also fails with invalid_grant, the merchant needs to re-authorize.

Implement exponential backoff for retries on 500 errors. Do not retry 4xx errors (except 429 if rate-limited).

Log correlation IDs. When submitting merchant data, include a correlationId so you can trace issues across systems.

Validate webhook signatures before processing any inbound webhook payload. Reject requests with invalid signatures immediately.

Handle array messages. The message field in API errors can be a string or an array of strings. Your error handling should accommodate both formats.

Respect rate limits. Implement client-side rate limiting for inbound webhooks to stay within the 100 requests per 60 seconds per marketplace threshold. Monitor for 429 responses and back off accordingly.

HTTP Status Codes#

OAuth Errors (RFC 6749)#

Error Codes#

Handling OAuth Errors#

API Errors#

Simple Error#

Validation Error with Field Details#

Common API Error Scenarios#

Webhook Errors#

Inbound Webhook Errors (Your Webhooks to OpenSylo)#

Outbound Webhook Failures (OpenSylo Webhooks to You)#

Rate Limit Errors#

Error Handling Best Practices#